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Preface 



The following are a list of some of the major changes evident in Version 6.0 as compared to Version 5.0: 

• General changes: 

o Support for Sun2/50's, Sun-3's and VaxStation-irs. 
o Better documentation: as you can see... 

• Lots of new commands, including: 

othe C program development environment, including cc68, 1d68, and build, an enhanced 
version of make 

o draw has been completely redone, including Postscript support 

o the Revision Control System 

ox11 sp, a variant of Lisp 

o The family of TeX document compilers, including tax and 1 atex (sorry, no sources) 

• New or changed services: 

o Global authentication services: Users now authenticate themselves once and need no longer 
authenticate each "session" independently. This is implemented by a combination of a global 
authentication server and V-to-UNIX "correspondence tables" maintained by the V servers 
running under UNIX. 

o Decentralized object naming: Local name servers have been eliminated in favor of each manager 
maintaining the name space of the objects it manages. Objects arc located with group IPC. 

o Group IPC: logically, messages are now sent to groups of processes, rather than to individual 
processes. ("Singleton" groups arc, in fact, special cased.) This permits a sender to send one copy 
of a message, but have it delivered to multiple recipients, in response to which multiple replies 
may (and can) be received. 

o"RAM disk'*: A V-storage-scrvcr-compatiblc server whose files are stored in main memory. 
Useful for temporary files and the like. 

This reference manual attempts to be as faithful to the indicated release of the system as possible. 
Unfortunately, there arc almost certainly many errors — most frequently errors of omission. The typical 
solution to this problem is to read the source code, but this too has its problems. The V-Systcm is the product 
of a research effort and is constantly undergoing revision. It has not always been possible to keep released 
and experimental versions strictly separated. Often, the source will include conditionally compiled code, or 
declarations for constants and dala types that arc not fully supported in the released version of the system. 
'ITicrcforc, programmers should be wary of using features found in the code that arc not documented in this 
manual. In brief: 

Warning: Any pan of the V-Systcm may change without notice. As a result, this document should be regarded strictly as 
advisory. 

Notes for installing die V-Systcm arc to be found in Appendix C. 

Contributing authors include Lance M. Bcrc, Eric J. Bcrglund, Per Bothncr, Kenneth P. Brooks, David 
R. Chcriton, Stephen R Dccring, J. Craig Dun woody, Judy L. Hdighoffcr, Ross S. Finlayson, Cary Gray, 
Bruce L. Hitson, David R. Kaclbling, Keith A. Lantz, Timothy P. Mann, Thomas Maslcn, Robert J. Naglcr, 
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William I. Nowicki, Joseph Pallas, Paul J. Roy, Jay Schuster, Michael Stumm, Marvin M. Theimer, 
Christopher Zulccg, and Willy Zwaencpoel. 

The following arc trademarks of Digital Equipment Corporation: DEC, DECSystem-20, Tops-20, Unibus, 
Vax, VAXStation, VMS, VT-100, and MicroVAX. 

Ethernet is a trademark of Xerox Corporation. 

Sun Workstation is a trademark of Sun Microsystems Inc. 

Unix is a trademark of AT&T Bell Laboratories. 

V-System is a trademark qf Leland Stanford Junior University. 
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Introduction 



The V-System is a message-based distributed operating system designed primarily for high-performance 
workstations connected by local networks. It permits the workstation to be treated as a multi-function 
component of the distributed system, rather than solely as a intelligent terminal or personal computer. 
Ultimately, it is intended to provide a general-purpose program execution environment similar to some 
degree to Unix. The programs are intended to interact with each other, and with programs running on 
traditional timesharing systems, to produce an integrated distributed system. 

1.1. The Hardware Environment 

The V-Systcm is targeted for a hardware environment consisting of (see Figure 1-1): 

• powerful workstations with: 

o a high-resolution (e.g. 1024 by 1024) raster display; 

o a general-purpose 1 MIPS (or better) processor; 

o 2 Mbytes or more of local memory; 

o a large (greater than 20 bits) virtual address space; 

o a graphics input device, such as a mouse: and optionally, . 

o a disk, 

which, typically, will be dedicated to a single user at a time; 

• a fast (greater than 1 MHz) communications network that will link the workstations; 

• a number of dedicated processors providing printing, file storage, general computation support, and 
other services; and 

• access to time-sharing or special-purpose computers and to long-haul computer networks. 

This release of the system runs on Sun and VaxStation workstations interconnected by cither 3 or 10 Mb 
Ethernet. "Guest-level" implementations arc available for 4.2BSD and 4.3BSD Unix systems (with Stanford 
enhancements). 

1.2. The User Model 

One of the most important functions for the workstation is to provide state-of-the-art user interface support. 
The workstation should function as a front end to all available resources, whether local to the workstation or 
remote. To do so, the V-Systcm adheres to three fundamental principles: 

1. The interface to application programs is (reasonably) independent of particular physical devices or 
intervening networks. 

2. The user is allowed to perform multiple tasks simultaneously. 

3. Response to user interaction is fast 

Adhering to these principles, the V-Systcm supports a reasonably sophisticated "window system". Multiple 
executives or shells may be run simultaneously, each of which may run one application in the "foreground" 
and any number in die "background" (a la the UNIX C-shcll). Applications may run local to the workstation 
or remote. Each application may be associated with one or more separate virtual terminals, each of which may 



V-Systcm 6.0 Reference Manual 17 June 1986 



1-2 



Introduction 



Cluster 
Network 



Cluster 
Network 



Cluster 
Network 



User 



User 




User 



User 




9©m 



E 



User 



User 



□ 



B 



□ 
Bf 



w 
w 



GH3-CZ 



Q 



Users 



&{ 



Users 






Trunk 
Network 



Long-haul 
Network 



User 



96-E] 




Gateway 
Workstation 

Printer Server 

File Server 

T t- - Timesharing System 

Figure 1-1: A workstation-based distributed system, 
be used to emulate cither a VT-100 terminal or a 2-D "structured graphics" terminal. 



1 .3. The System Model 

The V-Systcm adheres to the server model: 'Hie world consists of a collection of resources accessible by 
clients 1 and managed by servers. A server defines the abstract representation of its resources) and the 
operations on this representation. A resource may only be accessed or manipulated through its server. 
Because servers arc constructed with well-defined interfaces, the implementation details of a resource arc of 
concern only to its server. Note that a server frequently acts as a client when it accesses resources managed by 
other servers. Thus, client and server arc merely roles played by a process. 

Clients and servers may be distributed throughout the (intcr)nctwork. By default, access to resources is 
network transparent', a client may access a remote resource with the same semantics as it accesses a local 
resource. ITic result is an environment in which clients may communicate with servers without regard for the 



*A client is a program requesting access to a resource, typically on behalf of a human user. 



V-Systcm 6.0 Reference Manual 



17 June 1986 



The System Model 



1-3 



topology of the distributed system as a whole. However, we do not intend that a client cannot determine or 
influence the location of a particular resource, rather that a transparent mechanism is available. Moreover, we 
allow for clients and servers that were not written with network-transparent access in mind. 

Architecturally, then, the V-System consists of a distributed kernel and a distributed set of server processes. 

1 .3.1 . The Distributed Kernel 

The distributed kernel consists of the collection of kernels resident on each participating machine (see 
Figure 1-2). Each host kernel provides process management, interprocess communication, and low-level 
device management facilities. All other operating system services are implemented as (collections) of 
processes outside the kernel. A host kernel may be implemented at a base level (as on the Sun workstation) or 
a guest level (as under 4.2BSD). 



workstation 



r 



kernel 



IL 



kernel 



distributed 



kernel 



kernel 



interkernel protocol 



Ethernet 



Figure 1-2: The distributed V kernel. 

The host kernels arc integrated via a low-overhead interkernel protocol (IKP) that supports transparent 
interprocess communication between machines. IKP is a reliable request- response protocol, intermediate in 
complexity between conventional datagram and virtual circuit protocols. 

1.3.2. Servers 

Servers include: 

virtual graphics terminal server 

Provides all terminal management functions, including VT-100 emulation and 2-D 
graphics. One per workstation. 

internet server Provides network and transport level support for traditional network architectures, namely, 
ARPA Internet and Xerox PUP. Higher-level protocols, such as TKI.NKT, arc provided as 
separate packages that interface to the internet server. 
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pipe server Provides asynchronous, buffered communication facilities similar to Unix pipes. 

team server Provides team creation, destruction, and management One per workstation. 

exception server Fields process exceptions and dispatches them to registered handlers, such as debuggers. 
One per workstation, 

storage server Provides file storage. 

device servers) Interfaces to a specific physical device, such as the console, mouse, serial line, or disk. 

1 .4. The Application Model 

In general, it is just as easy to write applications to run under the V-System as it is to write applications to 
run under any traditional operating system, such as Unix. A standard program environment is defined, the 
principal instance of which is the C program library. The C library provides runtime support for standard C 
and UNIX-like library functions, including both byte-stream and block-I/O facilities (sec Figure 1-3). In 
effect, these libraries can be used to "hide" the underlying V-Systcm kernel calls, thus facilitating the porting 
of existing C programs. 
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Figure 1-3: Client interfaces to the V-System 

On the other hand, an application programmer may choose to take advantage of the enhanced facilities 
provided by the V-Systcm. ITicsc facilities fall in two major categories: user interaction and concurrent 
programming. Additional advantage accrues from the fact that applications may be distributed across 
multiple machines. 
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1 .4.1 . User Interaction 

With respect to user interaction, the V-System provides two principal enhancements over traditional 
UNIX-like systems. First, a program may manipulate multiple virtual terminals (windows) simultaneously. 
Second, an application may employ structured graphics. Specifically, a graphical object can be defined in 
terms of other objects, which can in turn be defined in terms of yet other objects. Thus, the VGTS supports 
structured display files rather than the more common segmented display files. The resulting virtual graphics 
terminal protocol (VGTP) is a high-level object-oriented protocol that minimizes both the frequency of 
communication between application and VGTS and the amount of data transmitted at any one time. 

1.4.2. Concurrent Programming 

Using the distributed kernel well requires understanding the model of processes and messages that the 
kernel provides, and how they are intended to be used. Processes represent logical activities within the 
application. They are intended to be sufficiently inexpensive to allow the use of multiple processes to achieve 
the desired 'evel of concurrency. In particular, multiple processes may share the same address space or learn, 
to facilitate fine-grain sharing of code and data. A team must be entirely contained on a single machine. 

Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique 
process identifier that is used subsequently to specify that process. 

Synchronous message-passing facilitates communication between processes that looks to the sender like a 
procedure call. That is, the sender blocks until a reply to his request is received. Greater flexibility is 
provided to the receiver to allow scheduling of requests. Messages are addressed to the process identifier of 
the recipient; there is no concept of a mailbox or port distinct from a process. 

Messages arc short and fixed-length. To facilitate transfer of large amounts of data, a separate data transfer 
facility is provided. Specifically, a process can pass, in a message, access to an area in its team space. This 
facility follows the procedure paradigm in being used primarily to access what arc logically "call-by- 
refcrencc" parameters. Synchronization between the two processes involved in the data transfer is guaranteed 
by virtue of the fact Uiat the recipient will not reply to the sender (and hence awaken him) until the transfer is 
complete. 

The kernel also provides process groups and group interprocess communication. Each process can create, 
join, and leave groups dynamically, and can belong to many groups simultaneously. A message sent to a 
group is delivered reliably to the first group member to reply, and unreliably to the rest. Replies subsequent 
to the first may be received (unreliably) by the sender, or ignored, at its option. 

Process scheduling is strictly priority- based. The effective priority of a process is the sum of its process 
priority and its team priority. Team priorities are dynamically varied by the team server to provide ume- 
slicing. 

1 .4.3. Classes of Applications 

From the previous discussion it should be apparent that applications may run local to the user's workstation 
or on any other host accessible via die various network protocols. Ultimately, all applications must 
communicate with the user via the virtual graphics terminal server (VGTS) resident on the user's workstation. 
The application interface to the VGTS is referred to as the virtual graphics tcnninal protocol (VGTP). 

The VGTP is constant over all applications. However, some applications have no knowledge of the VGTP 
and some applications arc running on machines that do not support the interprocess communication 
mechanisms underlying the VGTP. The following situations arise (sec Figure 1-4, in which each intcr- 
machinc arc is labeled with an example (presentation protocol transport protocol) pair): 

• Application A runs on the workstation and communicates via the VGTP. Current examples include text 
editors, document illustrators, and design aids, many of which arc documented here. 

• Application B runs on a machine that supports V kernel services, specifically, network- transparent 
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Figure 1-4: Some possible applications. 

interprocess communication via IKP. B communicates with the VGTS via the VGTP, as in the case of a 
application A. 

• Application C runs on a machine that docs not support IKP, but docs support a traditional network 
architecture such as the Internet protocol family. In addition, a VGTP interface package is available 
that encapsulates the VGTP within the appropriate transport protocol. Similarly, a local agent for the 
application, C* is created on the workstation to dccapsulatc the VGTP. Thus, the application may still 
be written in terms of the VGTP and neither it nor the VGTS have any knowledge that the other is 
remote. Our VLSI layout editor, for example, can be run in this fashion under Vax/Unix. 

• Application D has no knowledge of the VGTS or the VGTP; it wishes to regard the workstation as just 
another terminal. The local agent, D\ is "user Ti-i-NhT" and performs the appropriate translations 
between TCLNirr and VGTP. Any pre-existing application that runs on a remote host falls into this 
class. 

• Application ZT is distributed between the workstation and one or more other machines. The local agent, 
E\ is responsible for representing the multitude to the VG IS. It must perform the appropriate set of 
protocol conversions indicated above. In addition, it may wish to perform application-specific 
functions, such as caching. In that case, the protocol used to communicate with die remote applications 
may require more than simple transport service. The Amaze game documented herein is an example of 
such an application. 
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1.5. Outline 

The remainder of this manual consists of four parts: 
Part 1 Using V: describes the user interface and available application programs. 

Part 2 V Programming: defines the V-Systcm program environment in terms of the existing C 

program library. 

Part 3 V Servers : defines the standard message formats, request and reply types, and protocols; 

presents the various server-specific protocols; and gives some implementation details. . 

Part 4 Appendices: a V-Systcm bibliography, notes on programming style, installation notes, and 

a list of where the various library functions are defined. 
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User Interface Overview 



This chapter presents an overview of what it is like for the user to interact with the V-Systcm. Details of 
terminal emulation or graphics support are not discussed, since that is best described by the programmer's 
interface in Chapter 29. Rather, the basic stylistic conventions are presented, including an overview of how 
applications' actions are manifested to the user. Also included is a discussion of the the basic architecture of 
the user interface, in the hope that it will enable the user to better understand the style of interaction and the 
facilities available to him. The user who is "in a hurry" to get started may skip this discussion, at least on first 
reading, and begin with Section 2.2. The following chapter discusses command interpretation in some detail. 

2.1 . The User Interface Architecture 

In a typical operating system, the user is presented with the illusion of interacting with a single, unified 
front end, often referred to as an "executive" or "shell". However, in contemporary workstation-based 
systems, this front end actually provides three basic levels of interaction: 

1. device I/O: Manipulation of input devices and generation of output on output devices. 

2. command interpretation: Command (or argument) specification and response handling, and invocation 
, of applications. 

3. window management: Management of multiple simultaneous applications (in separate "windows"). 

Rather than combine these three levels of function in one module, the V-Systcm distinguishes three 
separate software components — respectively: 

1. the workstation agent, 

2. the executive, and 

3. the workstation manager. 

This separation was inspired by a desire to be able to configure each component independent of the others. 
While this release of the V-Systcm docs not reflect the ideal realization of this separation, it nevertheless fits 
the basic framework. 

Warning: The workstation agent was originally referred to as the terminal agent. The two terms arc used interchangeably. 

2.1 .1 . Workstation Agents 

The workstation agent provides the lowest-level interface between the hardware and the rest of the system. 
One of its principal functions is to hide any idiosyncrasies of that hardware — through a virtual terminal 
interface. 

2.1 .1 .1 . Virtual Terminals 

Rather than dealing with the "raw" hardware, applications interact with a virtual terminal. They request 
input from a virtual keyboard or mouse, for example, and write output to a virtual store. Depending on the 
"class" of real terminal (workstation) being emulated, the characteristics of the virtual input and output 
devices may vary widely. In the simplest implementation, each workstation agent emulates exactly one class 
of real terminal: emulating a different terminal requires a new workstation agent. More sophisticated 
workstation agents emulate multiple classes of terminals simultaneously. Note that the number of classes of 
terminals emulated is independent of the number of virtual terminals being emulated at any one time. 
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Historically, the most common class of terminal emulated has been the page-mode (character) terminal — 
exemplified by the Dec VT-100. Even in this case, the workstation agent can be thought of as emulating 
different types of terminals, corresponding to the various input and output modes provided by a VT-100 — 
character-at-a-time versus block transmission, local editing facilities, and the like. In general, the workstation 
agent, through its virtual terminals, provides a set of facilities that might be referred to as "cooked I/O" — 
ranging from character echoing to line-editing to page-editing to graphics-editing. These facilities are enabled 
and disabled on a virtual terminal by virtual terminal basis. 

True to its name, a virtual terminal need have no physical, real-world manifestation. In particular, it is 
possible to write output to a virtual terminal without seeing that output displayed on the screen. Hence, any 
application may run and change the store of any virtual terminal at any time. 

While it is common for multiple applications to be generating output simultaneously, it has historically (if 
erroneously) been thought less desirable to permit the user to direct input to multiple applications 
simultaneously. True to this historical bias, the V-Systcm currently restricts input to one application at a time. 
We refer to the application and associated virtual terminals as being "selected" (for input). Selection for 
input has no effect on the underlying application's ability to generate output. As with output, however, it is 
possible to generate keyboard input for a virtual terminal without having the virtual terminal mapped to the 
screen; users should be wary of the possible consequences! 

2.1.1.2. Views 

In order for the user to actually see the output from or generate graphical input to a virtual terminal, the 
virtual terminal must be mapped to the screen through a view. A view defines the portion of the virtual 
terminal's store that should be displayed, the area on the screen in which it should be displayed, and the 
transformation that should be applied when mapping the store to the screen. Using traditional graphics 
terminology, the store is referred to as the display file, the portion of the store is a window, the area of the 
screen is a viewport, and the transformation is a viewing transformation. Viewports arc invariably rectangular, 
although there Is no conceptual reason for this to be the case. 

Typically, an application will create one view of a virtual terminal at the same time it creates the virtual 
terminal. Nevertheless, views arc maintained as entities distinct from virtual terminals because, in general, 
each virtual terminal may have more than one view associated with it. When using the ,VGTS, for example, 
the same picture, maintained as one entity by the program, may appear in two separate viewports on the 
screen, possibly with different viewing transformations. That is, a second view may look upon a different 
portion of the virtual terminal's store from the first, or at a different magnification. 

Note: licciusc a view is the physical manifestation or a virtual terminal on the display screen, we will tend to use the term 
"view" rather than "virtual terminal" when discussing screen management issues. Where necessary to be even more 
specific we will use the term "viewport". 

So. a virtual terminal may be associated with more than one view. On the other hand, because the virtual 
terminal is independent of its physical manifestation, there need be no views associated with it. Destruction 
of all views docs not in any way affect the virtual terminal, though it will make it rather difficult for the user to 
sec what is going on. 

One common policy is that views arc the domain of the user. A program that creates a virtual terminal 
should create a view of it, so that the user knows that it exists, but aller that, in the ordinary course of tilings, 
the program should leave die view alone. The program should not depend on die continue existence of that 
view, nor need it be aware of any other views of the virtual terminal that the user chooses to create. Let the 
user decide where on the screen he wants views to be, and how big, and with what viewing transformations. 
That is what the workstation manager is for. 



5 
Unfortunately, traditional "window system" terminology tends to use the word "window" to mean any or all of window (as just 

defined), viewport, view, or virtual terminal. 
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2.1.1.3. V-System Agents 

The V-Systcm currently supports two workstation agents, the simple terminal server (STS) and the virtual 
graphics terminal server (VGTS). The STS provides basic text terminal emulation by making the workstation 
appear as a single, traditional, page-mode terminal — compatible with ANSI standard X3.64. 3 Character 
echoing and line-editing are optional. The STS is used principally to interface to ASCII terminals, but it can 
also be used over remote terminal connections and as the interface to the normal workstation keyboard and 
display. .■•:■•- 

The VGTS provides considerably greater functionality, including support of what is commonly referred to 
as a window system (more on this later). Any "window" may emulate the same type of terminal provided by 
the STS. Alternatively, a window may emulate a (structured) graphics terminal that provides roughly the 
facilities available in the ISO standard Graphical Kernel System, together with rudimentary modeling 
facilities in the form of structured display files. Thus, the VGTS provides simultaneous support for two very 
different types of real terminal. Each virtual terminal may have any number of views associated with it Any 
number of views of any number of virtual terminals can be mapped to the screen at the same time. 
Applications are unaware of the number of views or what is being displayed in them, except insofar as 
graphical input events return the appropriate world coordinates. The VGTS is used when it is desired to 
make the best use of devices typically found on contemporary workstations — such as bit-mapped displays, 
encoded keyboards, and mice. 

While the abstractions for keyboard and mouse are common across (existing) virtual terminals, the 
abstractions for the store arc quite different, as discussed in Chapter 29. When necessary to distinguish the 
two classes of virtual terminals currently supportcd/wc will refer to the type of virtual terminal that emulates 
an ANSI standard terminal as an ANSI virtual terminal (AVT) and the type of virtual terminal that emulates a 
structured graphics terminal as a structured graphics virtual terminal (SGVT). 

Warning: The "store" of an AVT is referred to as a pad Unfortunately, that term has been most frcqucnUy (and 
erroneously) used as a placeholder for the complete A VT abstraction. While this manual attempts to use each term where it 
is appropriate, the code uses "pad" almost exclusively. Consequently, many of the routines described herein also refer to 
"pad". Similarly, the term "virtual graphics terminal" (or VGT) has been used almost exclusively in the code, rather than 
the term "structured graphics virtual terminal". In both cases, we trust the reader will be able to make the appropriate 
semantic substitutions. 

The bulk of the discussion to follow assumes use of the VGTS. 

2.1 .2. Workstation Managers 

The workstation manager permits the user to control multiple simultaneous executives — with 
accompanying applications. Through it executives arc created and destroyed, programs arc interrupted and 
killed, and both virtual tcinninal and views arc manipulated. With respect to the last, in particular, the 
workstation manager is the module that enforces the constraints on view management that the user desires. 
For example, it enforces the precise position and front-to-back "ordering" of viewports. 

It is crucial to appreciate the distinction between workstation managers and workstation agents. The 
manager exerts "control" over the "facilities" provided by the agent, while at the same time using those 
facilities to interact with the user. Different users may want different styles of control. For example, one user 
may prefer to specify all views manually, whereas another user may prefer the system to determine the "best" 
view automatically: one user may prefer his viewports to be tiled, whereas another may prefer them to 
overlap, llicsc styles arc independent of the basic facilities provided by the workstation agent 

In principle, it should be possible to define the ideal workstation manager, independent of all workstation 
agents. But, just as workstation agents arc limited in practice by the classes of real terminals they support, 
workstation managers arc limited in practice by the available classes of workstation agents, For example, the 
VG TS comes with a large and powerful workstation agent, called the view manager, which is accessed via 



mTic most widespread example of a terminal adhering to this standard is the Due VT-100. 
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popup menus. Many of its commands require the user to select or position viewports on the screen. Such 
interaction works best in an environment with a mouse, for example, yet some workstation agents may not 
provide an efficient emulation of a mouse. The STS, on the other hand, has only a trivial vestige of a 
workstation manager. Its primary function is to guarantee the existence of one executive running on the 
terminal at all times. _ # 

2.1.3. Executives '; 

Workstation agents and managers provide the basic facilities by which the user interacts with the 
workstation. But little has been said about how the user actually specifies commands and applications. In 
fact, these functions are provided by executives (or shells). 

Some systems permit only one executive, often running only one application at a time, but sometimes 
capable of running multiple applications at a time — one in the "foreground" and the rest in the 
"background", for example. Under the STS, the V-Systcm provides one executive (of the latter variety). 
Under the VGTS, multiple executives are supported simultaneously; the view manager is responsible for 
creating (and destroying) them. , :u\>. ■■:.<:>■■■. 

; ■ . .-■ , .'■;:*.-.■ -■ • ■"■» :; ' !! irn. 

2.1.4. Summary 

We have outlined the basic concepts underlying the user interface to the V-System. The rest of this chapter 
discusses the more practical details of how the user actually interacts with the system via its workstation agents 
and workstation managers. Interaction with executives is discussed in the next chapter. 

2.2. Getting Started «s 

When you come up to an idle workstation, it may be in one of several states. If the screen is blank, it is 
probably running V, but idle. The VGTS blanks the screen on idle workstations after a few minutes of 
inactivity. Move the mouse slightly or press any key on the keyboard to restore the display. A previous user 
may have left one or more of his sessions (sec below) active. The command 

logout .. .j . 

will terminate them all and get you off to a fresh start. If the workstation is running something other than V, 
is dead, powered down, or die like, it will be necessary to reboot it, as described in the following paragraphs. 

2.2.1 . Booting the Workstation 

As previously noted, the V-Systcm runs on a variety of workstations. Booting procedures vary depending 
on the manufacturer and on the model. Section 16.1 describes in detail how to boot all of the workstation 
configurations supported with this release. The following is an overview that should cover most situations. 

2.2.1.1. VaxStations 

When in the PROM monitor VaxStations display a >» prompt If the workstation is not in tills state, press 
the halt button twice (once to put it in, once to bring it out). If this doesn't halt the machine, press reset. 
These buttons arc on the front panel of the VaxStation CPU. Once at the PROM prompt, the command b 
xqaO will cause the workstation to boot over the cthcrncL 

2.2.1 .2. SMI Workstations 

An SMI workstation in a random state can be reset to the PROM monitor by holding down the key in the 
upper left hand corner of the keyboard, and hitting the "A" key. ('Hie key in the upper left hand corner may 
be labeled cither Ll, sm -UP, or i-rask hoi- depending on the exact model.) There is no reset button on SMI 
workstations, so a very serious crash can make it necessary to power-cycle the workstation. 
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Once you have gotten into the PROM monitor, the next thing to do is to type the k2 command, which 
simulates a power-up reset (Shortcuts are sometimes possible, but k2 is the safest route.) After the power-up 
memory test is completed, the workstation will try to boot its default program. Most Sun workstations at 
Stanford arc configured to boot the V-System with VGTS. The bootstrap program first loads the 
workstation's configuration file (see Chapter 19) to find out what its defaults are. It next prints "V-System" or 
"xV-Systcm" to indicate whether the production or experimental version of V is being loaded, then prints the 
filenames of the kernel and initial team as it loads them. 

If you notice the workstation is not booting what you want it to, you can interrupt the autoboot with the 
reset key sequence described above, then type in the exact boot command you want Most of the time, one of 
the following simple commands will do the job: 

b Boots the default program. - M 

b V Boots the production version of the V-System, with the VGTS. 

b xV Boots the experimental version of the V-System, with the VGTS. ..,,„,> 

General boot commands and the V bootstrap loader are described fully in section 16. - ■ 

Note: Most SMI workstations at Stanford use the Sun-2 processor board, but a few Sun-Is have not been upgraded The 
above description is correct for SMI workstations with Sun-1 processors as well as Sun-2s, but the details of the general boot 
command and other prom monitor commands vary. The V kernel tickles a bug in the current Sun-3 proms. Rebooting a 
Sun-3 usually requires power cycling the workstation. 

2.2.1.3. Cadlinc Workstations 

A Cadlinc workstation in a random state can be reset to the PROM monitor by typing 
<CTRLXSIUFTXBREAK>, pressing the reset button, or (in desperation) power-cycling the workstation. It is best 
to try pressing the comma key on a Cadlinc's numeric keypad before resetting it. If the V kernel is active at 
that point this key instructs; it to turn off the mouse, necessary for proper operation of the PROM monitor. 
Otherwise, you may have to power cycle the workstation or keyboard to regain control 

On the Cadlinc, either kl or k2 will simulate a powcrup reset You may need to type the command twice 
for it to take effect The Cadlinc prom monitor uses n in place of b in the simple boot commands above. See 
section 16 far a full description of Cadlinc boot commands. 

All Cadlinc workstations use a version of the Sun-1 processor board. 

2.2.1.4. Rack-Mount Suns 

Suns that have an ordinary terminal as their console can usually be brought into the prom monitor by 
hitting the terminal's bri-ak key. Sometimes there is a reset button or switch attached. Some rack-mount 
Suns at Stanford contain Sun-1 processors; others use the Sun-2. Some boot using the n command; others 
use b. In most cases, the boot commands listed above will work, and the STS will automatically be loaded in 
place of the VGTS, but in general it is best to check with a wizard before rebooting a rack-mount Sun. , 

2.2.2. An Overview of Subsequent Interaction 

Note: "Hits section is somewhat redundant with Section 2.1 since it is assumed that many people will read it without reading 
that section! 

Once the user has booted his workstation he may communicate with one of two entities: an executive or the 
view manager. 'Hie user executes commands (application programs) from within an executive, which is 
similar to the UNIX C-shctl. The applications may run local to the workstation or remote. They may be 
written with the particular workstation in mind, or run in "terminal emulation" mode. They may require I/O 
modalities other than traditional text namely, graphics. Each application may be associated with one or more 
separate virtual terminals as discussed above. 

When die user wishes to initiate a new application concurrent with existing applications, he must first create 
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a new executive. To do so, the user communicates with the view manager. The executive serves as a 
command interpreter from which the desired application may be initiated. The user can create a new 
executive, with associated virtual terminal, at any time, asynchronous to any existing activities. When a 
particular application requires additional virtual terminals, it is free to create them. These virtual terminals 
will be deallocated when the application terminates. 

A virtual terminal is made "visible" by mapping it to the screen. Each such mapping is termed a view. 
When an application creates a new virtual terminal, the application may specify where on the screen the view 
should appear or the application may request that the user should specify the view interactively. Thereafter, 
the user may create as many additional views as he wishes. To some extent, he may manipulate views of the 
same virtual terminal independent of all other views of that virtual terminal, for example, pan or zoom one 
view independent of all other views of the same virtual terminals. All such virtual terminal management is 
performed via the view manager. 

2.3. VGTS Conventions 

When using the VGTS, views appear as white overlapping rectangles on the screen, with a black border and 
a "banner" across the top edge. The banner contains the following information: 

• a virtual terminal identifier 

• a view identifier 

• the "name" of the associated application (if any) 

Every view of every ANSI virtual terminal displays the text input cursor as a small black box. An additional 
cursor is associated with the mouse; it may change shape depending on what graphical input event is 
expected, for example. 

2.3.1 . Selecting for Input 

As discussed above, at most one application is selected for input at one time. At most one of its virtual 
terminals (usually an AVT) may be selected for keyboard input Any subset of its virtual terminals may be 
selected simultaneously for mouse input; the application may selectively enable and disable mouse input for 
each virtual terminal. 

All views of all virtual terminals selected for input (of any kind) display a "blackened" banner— white text 
on black background. In addition, the virtual terminal selected for keyboard input will display a flashing 
black box at the cursor. Unsclcctcd virtual terminals have whitened banners — black text on white 
background. 

2.3.2. Using the Mouse 

There arc a few conventions for using the mouse with the VGTS. First, we assume a three-button mouse. 
In the discussion that follows, the buttons arc labeled simply "left", "middle", and "right". 

Wc assume that there is always a cursor associated with the mouse. Wherever the term "cursor" is used 
without qualification, wc arc probably talking about the mouse cursor — rather than the keyboard cursor. 
Also, wc will often use the phrase "pointing to" to mean "the mouse cursor is in" or "the mouse cursor is 
pointing to". 

A "click" consists of pressing any number of buttons down and releasing them at a certain point on the 
screen. While the buttons arc down there may be some kind of feedback, like an object which follows the 
cursor. The click is usually only acted upon when all the buttons arc released, so if you decide you have made 
a mistake after pressing the buttons you can slide the mouse to some harmless position before releasing the 
buttons. Holding all three buttons down is also interpreted as a universal abort by most programs and the 
view manager. 'Hie click event is sent to the program associated with the view in which the event occurred 
(through its virtual terminal). 
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A "transition" consists of a press or a release of any combination of buttons. A transition event is sent to the 
program associated with the view in which the event occurred. Since it typically is acted on immediately, the 
VGTS provides no feedback and the universal abort feature described above does not work. 

2.3.3. The Screen Saveir 

The VGTS will automatically disable (blacken) the screen if no keyboard or mouse events have occurred 
within the preceding 10 minutes. This helps protect the screen's phosphor. The screen is rcenablcd by a 
subsequent keyboard or mouse event Note that other VGTS events will not reenable the screen, so. the 
screen save will work even if a program such as mon (which periodically updates the screen) is being run. 

2.4. Workstation Management 

Almost all workstation management functions are accessible via a set of menus managed by the view 
manager. The only exception is selection of an application for input Many view manager functions arc also 
available via "accelerators" — "appropriate" mouse clicks in "appropriate" places. Some functions are 
triggered by program-generated requests. We discuss each situation in turn. 

2.4.1 . Selection for Input 

Gicking the left or middle button of the mouse in a view of a non-selected virtual terminal will cause the 
associated application to be selected for input The view will be brought to the top. 

2.4.2. Using the View ManagerMenus 

The view manager menus can always be invoked by moving the cursor to the grey background area or to 
any view not selected for input (except in the banner area) and pressing the right button. The following 
commands arc available from the view manager menus. The commands are presented in alphabetical order, 
followed by a summary of what each (sub-)mcnu contains. 

2.4.2.1. View Manager Menu Commands 

Center Window Change the "window" associated with a view — without changing the position of the 
associated viewport Click any button at the position in the viewport that you want to 
become the center of the viewport Doing this to AVTs is almost always a mistake. 

Create Executive Create a new executive, with associated AVT.. The cursor changes to the word "Exec". 
When you press a button, an outline of the new AVT will appear, and will follow the 
cursor as you hold the button down. Lift the button up at the desired position, or press all 
three buttons to abort 

Note: Comes in two flavors, for two different default sizes of AVT (sec Set Alternate Exec Size 
below). 

Create View Create another view of an existing virtual terminal. Hie cursor changes to the word 

"View". Move the cursor to the desired position of any one of the four corners for the new 
viewport Hold any button down, and move the cursor to the diagonally opposite corner. 
An outline of the new view will follow the cursor as it moves with the button down. Let 
the button up, and then point at the virtual terminal that you would like to sec witli the left 
or middle button, or hit the right button and select the virtual terminal from the menu. 
Normally only used with SGVTs. 

Delete Executive Delete an executive. Click any button in any view associated with the executive. 

Delete View Delete a view. Click any button in the associated viewport 
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Warning: If you delete the last view of a virtual terminal, it does not destroy the virtual terminal or 
the process associated with it You can still create views of the virtual terminal by using the right 
button menu in the Create View command. 

Exec Control Select the submenu for executive and program control functions. A shortcut to the Exec 
Control menu is obtained by pressing both the middle and right buttons while the cursor is 
in the gray background or in a view not selected for mouse input 

Expansion Depth Set the "expansion depth" for a SGVT. For hierarchically defined graphical symbols, this 
determines how much (how deep) of the hierarchy will be displayed. If this causes some 
graphical item not to be displayed, its bounding box is displayed, possibly with a text name 
(if there is room). The default expansion depth is infinity, such that all levels will be 
expanded. Click any button in the view whose expansion depth you wish to set, then select 
the new expansion depth from the menu that pops up. 

Graphics Commands 

Select the submenu for graphics functions. A shortcut to the Graphics Commands menu is 
obtained by pressing both the left and right buttons while the cursor is in the gray 
background or in a view that is not selected for mouse input 

Interrupt Program Interrupt a program, forcing it into the debugger. Click any button in any view associated 
with the program. 

Kill Program Kill a program. Click any button in any view associated with the program. 

Make Bottom Push a view to the bottom, potentially making visible other views. Click any button in the 
desired view. A shortcut to this function is obtained by pressing the right button while the 
cursor is in the banner of the desired view. 

Make Top Bring a view to the top, potentially obscuring other views. Click any button in the desired 

view. Does not select the associated virtual terminal for input A shortcut to this function 
is obtained by pressing the left button while pointing to the banner of the desired viewport, 
which action action does select the virtual terminal for input 

Move Edges Change the viewport associated with a view by moving one or more edges. Scaling is not 
provided, so this also changes the window (the portion of the object being viewed), but 
without moving the object relative to the screen. Push any button down next to an edge or 
corner, move that edge or corner to the new position, and let the button up. The edge 
outline should follow the cursor as long as you hold the button down. 

Move Edges + Object 

Similar to Move Edges, but drags the underlying object around with the moved edge or 
corner. 

Move Viewport Change the viewport associated with a view by changing its position, but retaining its size. 
Press any button in the desired view. While the button is being held down, the outline of 
the viewport will move, following the cursor. Lift up the button at the desired position. A 
shortcut to this function is obtained by pressing the middle button while pointing to the 
banner of die desired view; the viewport outline will follow the cursor until the middle 
button is released. 

Redraw Erase and redraw the entire screen. Should be necessary only when low-level debugging 

information trashes the screen. 

Reset State Reset the state of an A VT. Click in any view of die AVT. This is equivalent to pushing the 

"reset" key on a VT-100 or most other page-mode terminals and is necessary only in 
extraordinary situations where the AVT appears to be "wedged". 

Set Alternate Exec Size 

Set the "alternate" size for executives. Type in the size to the VGTS window. Executives 
of the new size can then be created using the Exec Control submenu. 
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Toggle Grid • Toggle the background grid in a view of SGVT. Click once to turn the grid on if it is off, 
or off it is on in the view you select. The grid dots are every 16 screen pixels, and always 
line up with the origin. 

Toggle Paged Output Mode 

Enable or disable paged-output mode in a AVT. Click in any view of the AVT. 

Zoom Invoke "zoom mode" in an SGVT. The cursor changes to the word "Zoom". You can get 

out of this mode in two different ways: First, clicking the left or middle buttons when the 
cursor is inside a view of an AVT returns from the view manager and selects that AVT for 
input As a side effect that view is also brought to the top. Secondly, you can click the 
right mouse button. The cursor should change back to the normal arrow. 

The left and middle buttons in Zoom mode zoom out and in respectively. That is, the left 
button makes the object look smaller, and the middle button makes it look larger. You can 
remember this because the "outer" (left) button zooms out, and the "inner" (middle) 
button zooms in. A shortcut to this mode is available by clicking the middle and left 
buttons at the same time while the cursor points to the gray background or to a view not 
selected for mouse input 

2.4.2,2. Assignment of Commands to Menus 

The top-level view manager menu contains the following commands: 

Create View 
Delete View 
Exec Control 
Graphics Commands 
Make Bottom 
Make Top 
Move Viewport 

The "Exec Control" sub-menu contains: 

Create Executive {two flavors!) 

Delete Executive 

Interrupt Program 

Kill Program 

Reset State 

Set Alternate Exec Size 

Toggle Paged Output Mode 

The "Graphics Commands" sub-menu contains: 

Center Window 

Expansion Depth 

Move Edges 

Move Edges + Object 

Redraw 

Toggle Grid 

Zoom 

2.4.3o Summary of Accelerators 

The workstation management functions available though mouse clicks arc listed in Table 2-1. Sec also 
section 2.7. 
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Mouse 

Buttons Where Effect 
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In banner Make To P and select 

. x . In banner Move Viewport 

. . x In banner Make Bottom 

x . . In non-selected viewport Make Top and select 

. x . In non-selected viewport Make Top and select 

. . x In gray or non-selected viewport Top-level menu 

x x In gray or non-selected viewport Exec Control 

x . x In gray or non-selected viewport Graphics Commands 

x x . In gray or non-selected viewport Zoom 

xxx During any workstation management command Abort 

Tabic 2-1: Accelerators for workstation management functions. 

2.4.4. Program-generated Requests 

When a program requests the creation of a view, the VGTS enters the same interaction cycle as described 
for the Create View command above. However, since the virtual terminal will have been specified in the 
function call, you do not need to select the virtual terminal, and universal abort typically will not work. 

When a program requests the creation of an AVT, the cursor will change to the word "Pad" (sorry about 
that). At this point, hold down any button, and an outline of the viewport that will be created will be tracked 
on the screen. Position the viewport where desired, and let go of the button. 

2.5. Line Editing Facilities 

Keyboard input can be edited with Emacs-stylc line-editing commands. More specifically, the commands 
listed below arc available. CTRL-x means holding down the Control key and the x key simultaneously; ESC-x 
means striking the Escape key and then the x key. 
CTRL-a Move cursor to beginning of the command line. 
CTRL-b Move cursor back one character. 

crRL-c Kills the Break Process, usually the command running in the current executive. 
crRL-d Delete character under the cursor. 
CTRL-e Move cursor to the end of the command line. 
CTRL-f Move cursor forward one character. 

CTRL-g Abort the command. The line editor will pass the command line, followed by a CTRL-g, to die client 
program, which is responsible for detecting the CTRL-g and reacting to it (The standard executive 
responds to such a line by printing "XXX".) 

Ci'RL-h Delete the character before die cursor. Equivalent to the DHL key. 

CTRL-i Insert an appropriate number of spaces, to simulate a TAB character. Equivalent to the tab key. 

CTRL-k Delete the command line from the cursor to the end of the line. 

CTRL-t Transpose the two characters preceding the cursor. 

crRL-u Delete the command line up to the cursor. 

ctrl-w Delete from the cursor to the beginning of the current word. 

CTRL-z Causes an End of File indication to be sent to the application reading the line. This will terminate 
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the Executive if no application is running. 

ESC-b Move cursor to the beginning of the current word 

ESC-d Delete from the cursor to the end of the current word. 

nsc-f Move cursor past the end of the current word. 

ESC-h Delete from the cursor to the beginning of the current word. Same as CTRL-w. 

CR Return the line-edited text to the client Even if struck in the middle of the "line", the entire line 

will be returned. 

Printing characters are normally inserted at the cursor. . 

2.6. Paged Output Mode 

When paged output mode is on, the workstation agent stops writing to an AVT when the AVT fills up with 
output The workstation agent then displays the message "Type <space> for next page" in the banner and 
waits for the user to issue a command that unblocks the AVT. 

Most commands are optionally preceded by an integer argument k. Defaults arc in brackets. Star (*) 
indicates that the argument becomes the new default 

<space> Display the next A lines [current page size] 

z,Z Display the next k lines [current page size]* 

CR, LF Display the next k lines [1] 

q, Q Throw away all output until the next time input is sent to the application program. 

s Scroll forward k lines [1] 

S Scroll forward to the last line 

f Scroll forward k pages [I] 

F Scroll forward to die last page 

bs, del Erase the last character of die numeric argument 

Repeat the previous command 

If the user types a character that is not a valid command, the character is treated as a normal input 
character. If line-editing miodc is on, the CTRL-c and CTRL-z commands (see section 2.5) have their usual 
effect here. 

2.7. Sending Mouses Events to Text-oriented Applications 

Many applications exist mat have not been written expressly for the V-Systcm, but can be accessed via the 
text terminal emulation protocol. A few minor additions to this protocol permit applications to receive a 
number of mouse clicks as escape sequences that they may interpret as they wish. 'Hie precise escape 
sequences generated arc given in Chapter 29. 

A complete list of the events that generate escape sequences, and die use to which the UNIX EMACS text 
editor puts them, is given in Table 2-2. The actual escape sequences generated arc given in Section 29.2.2. 
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Mouse 

Buttons Emacs Interpretation 

1. M R 



x . . Position the cursor at the position of the click. 

x x . Set the mark to the clicked position. 

x . x # Delete from the mark to the clicked position. 

. x x' Insert the kill buffer at the clicked position. 

Table 2-2: Events that generate escape sequences. 

2.8. Emulating the Mouse withthe Keyboard 

For the benefit of hardware configurations without a working mouse, the VGTS can interpret certain 
keyboard escape sequences as mouse input 

2.8.1. Workstation Management 

The input virtual terminal can be changed by using CTRL-t (octal 036) followed by a single command 
character. The only command characters interpreted by the VGTS are 1-9 to select the given virtual terminal 
for input 

2.8.2. Graphics Events 

The VGTS also interprets certain character sequences as mouse movements or button transitions. 
However, the VGTS will only intercept these escape sequences if they are sent as a rapid burst of characters, 
as is the case when they arc sent by pressing a function key. If the escape sequences are typed manually, the 
VGTS detects the space between characters and passes them through in the normal fashion. 

The following is a list of the escape sequences used and the function keys with which they are normally 
associated on an ANSI (VTlOO-stylc) keyboard: 

ESC-[ A (ANSI Down Arrow) 

Move the mouse cursor down. 

ESC-[B (ANSI Up Arrow) 

Move the mouse cursor up. 

nsc-[C (ANSI Right Arrow) 

Move the mouse cursor to the right 

1-SC-[D (ANSI Left Arrow) 

Move the mouse cursor to the left. 

ESC-OP (ANSIPF1) 

Toggle the value of the left mouse button. The new value of the left mouse button is 
displayed in the view manager window. 

ISC-OQ (ANSI PR) 

Toggle the value of the middle mouse button. The new value of the middle mouse button 
is displayed in the view manager window. 

ESC-OR (ANSIPF3) 

Toggle the value of the right mouse button. The new value of the right mouse button is 
displayed in the view manager window. 

nsc-OS (ANSIPF4) 

Toggle mouse emulation mode. When mouse emulation mode is OFF, all escape 
sequences except this one arc passed through as normal, allowing the associated function 
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keys to perform application-defined functions. The new state of mouse emulation mode is 
displayed in the view manager window. 

When the VGTS receives input from a "real" mouse, this type of emulation is permanently disabled. If 
your mouse fails, you must use the "newterm" command to create a new VGTS in order to use mouse 
emulation. 

Warning: These sequences only work on Sun-100's. 

2.9. STS Conventions 

• 

The bulk of the discussion thus far has assumed the availability of the VGTS. However, there arc occasions 
when users may have the interact with the STS instead. In that case, the user sees exactly one view of exacdy 
one terminal associated with cxactiy one executive. That view occupies the entire screen. The user interacts 
with this executive exacdy as he would with an executive running under the VGTS. Line-editing facilities and 
output paging arc provided. 
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3.1. Introduction 

The V executive is the part of the V system that accepts user commands from the keyboard and causes them 
to be executed. It corresponds to the Unix shell or Tops-20 Exec. The executive is available as a program and 
as a service provided by the exec server. Each executive usually runs in a virtual terminal provided by the 
workstation agent — either the STS or the VGTS. See the description of the STS in section 45 and the 
description of the Exec Control menu of the VGTS View Manager in section 2.4.2. 

The basic operation of the executive is to read command lines and execute commands. The first field on a 
command line is the command name; the rest are arguments to be passed to the command. Fields are 
separated by spaces, except when quoted (see section 3.6.6). A command name can be a built-in exec 
command, the name of a file containing a program compiled to run under the V system, or the name of a 
program to be run on a server, such as Unix. The executive provides a simple search path mechanism for 
commands. By default, it looks first for a V program in the current context (i.e., current working directory), 
then in the [bin] context You can specify a different search path using the PATH environment variable 
(section 3.6.7). If the command is not found on your search path, the exec will try to execute it remotely, on 
the server that is providing your current context. 

The executive waits for each command to exit, unless the last field on the command line is the single 
character &. In this case, the command runs in the background, while the executive continues to accept 
commands from the keyboard. The View Manager and STS provide mechanisms for stopping or interrupting 
a command running in the foreground. A program running in the background may be terminated using the 
destroy command (see chapter 4). 

Other exec features arc described in section 3.6. 

3.2. Naming 

A context in the V system is similar to the directories provided by other systems such as Unix. Each process 
(and thus each executive) has its own current context, i.c, current working directory. A filename is normally 
interpreted in the current context, unless it begins with a square bracket ('['). The square bracket flags the 
name as being cither an absolute name, or a local alias. 

In V, the first component of an absolute name generally specifics the type of object or service being named. 
The second component often specifics a particular server. For example, 

[storage/pescadero]/etc/passwd 
names the file /etc/passwd on the storage server pescadero. The closing square bracket is optional 
here. Most servers accept it as an alternative to the standard slash character (V) used to separate name 
components. 

Users can define their own local aliases for contexts, using the define and undef 1ne commands. For 
example, 

define g [storage/gregor1o]/user/mann 
defines, [g] as an abbreviation for user Mann's home directory on the storage server Grcgorio. The 
command 

undeflne g 
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removes this definition. The command 

printdef 
lists the local aliases that are currently defined Several other standard aliases are automatically defined by the 
executive when you log in. These include 

[home ] The logged-in user's home directory. 

[sys] The directory containing standard V-System files. 

[bin] The directory from which standard V-System commands are loaded. Normally the same as 

[sys]b1n. 

[V] The directory containing standard production V-System files. The same as [sys] if you 

are running the production V-System. 

[xV] The directory containing standard experimental V-System files. The same as [sys ] if you 

are running the experimental V-System. 

[nontax] The "home" server used for program execution. Normally [team/local], the local 

team server. See section 3.6.9. 

When running with the VGTS, aliases defined in any exec created by the view manager arc global to all such 
execs, since all the execs run on the same team. A program run under the exec inherits a copy of the cxec*s 
aliases. Later changes to the exec's aliases do not affect it 

3.2.1 . Changing the Current Context 

The cd (change directory) command can be used to change the current context for an exec. The command 
format is 

cd pathname 
The pathname is interpreted in the (previous) current context If the pathname is omitted, [home] is assumed. 
When an exec Is created, its current context is set to the current value of [homej. 

The pwd command prints the absolute name of the current context 

3.3. Logging In and Out 

3.3.1. Login 
The login command is used to authenticate a user to the V-Systcm. The command format is 
login flags user name 
The optional flags arc described below. 

The login command prompts for a password. The password is not echoed when typed. An error message is 
printed if the user types an invalid name or password, or cannot be authenticated for some other reason. If 
authentication is successful, the given user is registered with. the exec server and team server as the primary 
user of this workstation. 'ITic exec then forces any guest programs running on the workstation to migrate 
elsewhere. 

The exec next defines the local alias [home] to be the user's preferred home context as recorded in the 
system authentication database, and undefincs all other user-defined aliases. Thus, if user Mann's home 
context is [storage/teton]/ds/mann, after logging in, he can refer to the file 



The message "Server not responding" indicates thai no authentication server could be contacted. ITic command authservor ft 
will start one locally, after which it should be possible to log in. 
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/ds/mann/phone-numbers under the name [home]phone-numbers. In this case it would be possible 
to get at the "root" directory on Teton by using a / immediately following the alias, for example, 
[home]/u$r/V/m1sc/t©rmcap. 

Next, the exec changes its current context to be the new value of [home]. Finally, the exec executes a 
command script from the file [ h ome ] . V 1 n 1 1, if such a file exists. 

The login command's behavior can be modified by specifying one or more of the following flags on the 
command line: 

-v Verbose flag. Commands in .Vinit are echoed as they are executed. 

-q Quick flag. Prevents .Vinit from being executed. 

-x Exclusive flag. Normally, when a user is logged in to a workstation, that workstation is 

registered as being unavailable for remote execution of commands, but if some other 
workstation insists on requesting remote execution there, the team server will still grant the 
request If the exclusive flag is given to the login program, the local team server is 
instructed to refuse all requests for remote execution. 

-r Remote flag. Register the workstation as being fully available for remote execution, as 

though no one were logged in. 

-f Finish flag. Allow guest programs currently executing on the workstation to finish. If this 

flag is not given, guest programs arc forced to migrate to another workstation. 

After a user has logged in to a workstation, all further execs created on that workstation using the View 
Manager run as that user. The su command can be used to authenticate individual execs as some other user. 
The command format is 

su username 
Like the login command, the su command prompts for a password, which is not echoed. However, it only 
authenticates the exec in which the command is typed. It docs not affect the exec server's record of the 
primary logged-in user, or perform any of the other actions of logl n. 

Execs created when no one is logged in to a workstation run as the unknown user. Most system servers place 
severe restrictions on what the unknown user is allowed to do. 

3.3.2. Logout 
Give the 1 ogout command when you arc done using a workstation. The command format is 
logout username ... 
where the user names arc optional. If no name is given, the user owning the exec in which the command was 
typed is logged out If one or more user names arc given, the given users arc logged out If the flag -a is 
given in place of the list of user names, all users with authenticated execs on the workstation arc logged out 
('Hie latter two options arc restricted to the primary logged-in user.) 

1 .ogging out a user destroys all execs authenticated as that user, and hence all foreground programs run by 
that user. Do not log out if you want such programs to continue running. 

3.4. Remote Program Execution on a Unix Server 

If the executive fails to find an appropriate load file for a command, it will attempt to execute the command 
on the server providing its current context by invoking the f execute program. Thus, for example, when a V 
server on Unix is providing the current context all the standard Unix commands like finger, man, or ps are 
available. 'Hie output of the Unix command is printed on the standard output file. 

You can also supply input to remote commands. The character echoing and line editing on this input are 
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done on the workstation, not by the session server machine. 

Since both the input and output arc done through pipes, and input is a line at a time, many Unix programs 
which expect to be run on tty devices (such as emacs, more, etc.) do not work in this mode. Such programs 
can only be run by logging in to the Unix machine, perhaps using the V telnet program to connect to it (see 
chapter 4). 

The V servers do not provide execution of Unix commands to users who are not logged in to V or do not 
have a Unix account If the executive tries to execute a Unix command for such a user, the V server returns 
an "No permission" error. 

3.5. Remote Execution on V Hosts 

A command can also be executed remotely by designating either a specific remote V host or any remote V 
host A specific host can be specified cither by the process id of its team server or by its string name (e.g. 
sun-mj416). (Syntax details are described in 3.6.9.) Remote execution of this type is transparent to the user in 
that I/O is still directed to the local host 

3.6. Facilities for Command Specification and Modification 

The executive provides various facilities for specifying commands and for redefining various aspects of 
command execution. The syntax and semantics of each is described below. 

3.6.1 . Line Editing Facilities 

Command lines can be edited as described in Section 2.5. 

3.6.2. Pattern Expansion 

A command argument that contains one or more asterisks (*) is considered a pattern, and is replaced by a 
list of existing filenames that match the pattern, unless it is quoted with "" or • ' (section 3.6.6). 'lTic asterisk 
character matches any string of zero or more characters other than slash (/), right square bracket (]), or an 
initial period ( .). Other characters in the pattern match themselves. 

3.6.3. Command History References 

The executive maintains a history of the last 20 command lines that the user has typed in. These command 
lines may be referenced by typing the character I immediately followed by a prefix of the desired command 
line. ITius if the command line 

cp /ng/ng/V/cmds/exec/exec.c /tmp/exec.c 

was typed in, then it can be referenced by typing (for example) 

icp 

If a non-unique prefix is specified then the most recent command with that prefix is taken. Another special 
form of reference is 1 1, which references the previous command line. 

When a command line is referenced it is redisplayed for further line editing and verification. Thus in the 
previous example typing 

lep 
will cause the executive to display 

cp /ng/ng/V/cmds/exec/exec.c /tmp/exec.c 
with the cursor sitting at the end of the line. The user can then hit carriage return to rc-cxccutc the line or can 



7 June 1986 V-Systciu 6.0 Reference Manual 



Facilities for Command Specification and Modification 3-5 



edit it first to derive a new command. 

The command history will cause the executive to list the command lines it has stored in its history 
record. The most recently executed command will be at the bottom of the list 

3.6.4. Command Aliases 

Command names can be aliased by means of the al 1 as command. Thus, for example, typing 
alias e ved 

will cause the command name "e" to be replaced by "ved" in subsequent command lines. Note that aliasing 
is done only for command names and not for command arguments. (Remember that the command name is 
the first word of a command line.) 

Aliases specify a string for replacement of the alias word. Thus one can create aliases such as 

alles test /ng/mmt/test/testcopy -d 
Then typing something like 

test filel f1le2 
will cause the command 

/ng/mmt/test/testcopy -d filel f1le2 
to be submitted to the executive for execution. 

A list of all defined aliases can be obtained by typing alias without any arguments. The command 
unal 1 as is used to remove an alias definition. Specifying a new alias definition for a command name simply 
replaces the old one. 

3.6.5. I/O Redirection and Pipes 

I/O redirection and specification of pipes between two (or more) commands is done using the same syntax 
as is used by the Unix shells. Thus input can be redirected to come from a file by specifying 

cmd < file 
and output can be redirected to a file by specifying 

cmd > file 
or 

cmd » file 

The latter form specifics that the output should be appended to the file whereas the first form will overwrite 
any data already existent in the file. Hrror output can be redirected by specifying >? or »?. The forms >& 
and »& redirect both standard output and standard error to the same file. 

A special form of redirection is available for bidirectional files, such as the serial lines available on Suns. 
Specifying 

cmd <> file 

causes the command's input and output to be redirected to the same file. To be precise, the file is opened in 
FCRKATK mode, and standard output is redirected to the instance thus created. Standard input is redirected 
to come from an instance whose id is equal to the output instance id plus 1. This matches a convention used 
by several V-Systcm I/O servers. The form <>& also redirects standard error to the same instance as standard 
output 

Pipes can be set up between several commands by separating them with a |- on the command line. Thus, 
for example, the command line 

cmdl | cmd2 | cmd3 > log 
will create two pipes and redirect I/O so that the output of cmdl will be used as the input to cmd2, the output 
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of cmd2 will be used as the input to cmd2,and the output of cmd2 will be redirected into the file log. 

All the special characters described above must be surrounded by spaces for the executive to recognize 
them. Redirection clauses must appear after all arguments to be passed to the command. 

3.6.6. Quoting Command Arguments 

Sometimes it is desirable to include a space in a single argument to a command. To do this, put a pair of 
either single quotes ( • ) or double quotes (") around the argument An argument quoted by one of these may 
contain the other. Unmatched quotes arc matched by the end of the line. 

3.6.7. Environment Variables 

The command 

setenv var value 
sets the environment variable var to the character-string value value. (The latter should be quoted if it 
contains spaces.) As with local aliases for context names, environment variables are shared among all execs 
created by the View Manager, and are inherited by programs run under any exec. 

The command 

unsetenv var 
removes the definition of var, while the command 

pMntenv var 
prints its definition. The pr 1 ntdef command with no arguments prints all environment variables. 

A command argument that begins with a dollar sign ('$') is replaced by the value of the rest of the argument 
interpreted as an environment variable, if such a variable is defined. Otherwise the argument is left 
unchanged. 

When trying to execute a V command, the exec determines the search path to be used from the 
environment variable PATH, if it is set, as do all programs that use the standard V-Systcm program execution 
library routines. The value of PATH should be a list of context names separated by spaces. The default path, 
used if PATH is not set, is "./ [bin]". 

3.6.8. Concurrent Commands 

Commands can be specified as being concurrent by including an & at the end of the command line. This 
causes the executive to return immediately to the user for another command rather than waiting until the 
current command completes. Also, while nonconcurrcnt (foreground) commands arc terminated if their 
executive is deleted, concurrent (background) commands will continue even if the executive that initiated 
them goes away. In fact, concurrent commands continue to execute even if the user that initiated them logs 
out. 

The & must be preceded by a space for the executive to recognize it 

3.6.9. Execution of Commands on Another Host 

Commands can be designated to execute on another host by including 
9 <host-designation> 
on the command line. Here <host-designation> can be one of three things: 

• Hie hexadecimal process id of the host's team server. This must given in the form Oxpid, i.e. as the 
characters Ox followed by the hex process id. 
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• The string name of the host, e.g. sun -mj 430. 

• The string any, designating any suitable V host other than the local one. A suitable host is defined as a 
host on which no one is logged in, and whose unused memory and CPU time meet certain minimum 
requirements. 

Remote execution, is transparent to the user in that the I/O of the command is still directed to the local host 
and will be displayed in the same manner as if the command were executing locally. 

The § sign must be surrounded by spaces for the executive to recognize it The remote execution clause, if 
present, must follow all arguments to the command (but may be intermixed freely with redirection clauses). 

Another way to specify that commands should be executed remotely is to use the ex command to change 
the exec's current execution context-Xhat is, the server (and context) where commands arc executed when a 
remote execution clause is not given. The command format is 

ex [t earn/ hostname"] 

Giving the ex command with no arguments resets the execution context to [homex], the exec's "home" 
execution context, which is normally [team/local ]. The command 

pwx 
prints the name of the current execution context 

3.7. Support for Heterogeneous Processors 

The V-System currently runs on machines with two different types of processor: the Motorola 68000 family 
and the DEC Vax family. More processor types may be supported in the future. Thus, several versions of the 
same V program may exist each compiled for a different processor. 

Different versions of the same V program that appear in the same directory may be distinguished by a 
machine-specific file-name suffix. This suffix is ".m68k" for Motorola 68000-bascd machines (in particular, 
Sun workstations), and ".vax" for the Vax. Note, in particular, that the directory for installed V-Systcm 
command binaries (at Stanford, /usr/V/b1 n) contains two such versions of almost every command. When 
searching for a command binary, the executive automatically searches for a file name both with and without 
an appropriate machine-specific suffix. 'Ilius, it is not necessary for the user to enter a machine-specific suffix 
when typing a command to the executive. This is true even if the command is executed remotely (sec section 
3.6.9) on a host with a different processor type. 

In light of the above, the executive's search path mechanism needs to be explained further. When a 
command is to be executed on a specific host (that is, one that is known in advance), then the executive looks 
down the search path, until it finds a version of the command that can be executed on this particular host 
This is the usual case. When a command is to be executed on an arbitrary' host ("8 any"), then a slightly 
different mechanism is used. In this case, the executive looks down the search path until it finds any version 
of this command. It then determines ail versions of the command that exist in this location, and selects a 
suitable remote host that is able to execute one of these versions. In most circumstances the difference 
between these two mechanisms will not be noticeable. 
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4.1. Workstation Commands 

The following briefly summarizes the currently available commands for V. 

addcorr Add correspondences from your V user identity to UNIX user accounts. Each V user can 

correspond to one account on each local UNIX machine that is running a V/UNIX server. 
The V superuser can add correspondences for other users as well as itself. See Chapter 43 
for more information about user correspondences. 

amaze A multi-person distributed game. Does not (yet) run under the VGTS. See Chapter 5. 

ar Constructs library files ("archives"). See the UNIX manual for documentation. 

biopsy Prints information about all the processes on the workstation, sorted by team. Several 

options are recognized. The -I option also includes the filename from which each team was 
loaded. (This generally makes the output longer than one screenful.) The -t option 
followed by a pid or the suffix of a team's filename will cause information to be printed 
only about the team associated with the pid or filename. More than one pid or filename 
can be specified - information for each will be printed. To obtain detailed information 
about one or more processes, invoke biopsy with just the pid(s) of the relevant processes). 

biteompile Converts human readable bitmap specifications into initialized C data structures. Usage: 

bitcompile [ options ] [ file ]. 

The file argument specifies the source, otherwise standard input is used. Output goes to 
standard output by default 

The following options are interpreted by bitcompile: 

-DBIG.ENDIAN 

Order the bytes (and bits) of the bitmap for big endian machines. This 
is the default 

-DBLACKJS.l 

Generate bits of 1 for black. This is the default 

-DBLACKJSJ) 

Generate bits of for black. 

-DCOLUMN.ORDER 

Generate bitmaps as columns of 16 bit words. 

-DLITTLE.ENDIAN 

Order the bytes (and bits) of the bitmap for little endian machines. 

-DNOHDR Do not place a header before each output bitmap. 

-DROW.ORDER 

Generate bitmaps as rows of 16 bit words. This is the default 

-DSUN100FB 

Generate bitmaps for (the current implementation of) SUN 1 frame 
buffers. This is equivalent to specifying -DCOLUMN.ORDER. 
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-DSUN120FB 



bits 
boise 



build 
cat 

cc68 

cd 
checkers 

checkexecs 



■DVAX 



-oftle 



Generate bitmaps for (the current implementation of) SUN 2 frame 
buffers. This is equivalent to specifying -DCOLUMN_ORDER. 

Generate bitmaps for (the current implementation of) Micro Vax frame 
buffers. This is equivalent to specifying -DUTTLEJiNDIAN 
-DBLACKJSJ). 



Send the output to file. 

A program for manipulating (e.g. hand-editing) bitmaps and fonts. See Chapter 7. 

Prints Mies on the Boise laser printer. 

Several switches are allowed, preceding the filenames: 

-r Print rotated, that is, in landscape (horizontal) mode. 

■n name Use name to label the output If this option is not given, the user's name 
is fetched from the system authentication database. 

-b banner Use banner in the "File:" field instead of the filename. 

-h hostname Host name to use instead of "V-System". 

•mmode Print mode. Possible modes are 

Line printer. For printing ordinary text files. The 
default unless the filename ends in ".dvi" or ".press'*. 

1 DVI. For printing TeX output The default if the 
filename ends in ".dvi". 

2 Press. Not implemented. The default if the file 
name ends in ".press". 

3 HP2680a. For files in HP2680a "spool file" format 

-w File is in the Sail ("WAITS") character set instead of standard ASCIL 

(Line printer mode only). 

-W File is in the TeX character set instead of standard ASGIL All 

characters with the high-order (8th) bit set are treated as printing 
characters after the high-order bit is stripped. This feature permits 
access to the printing characters "hidden under" the ASCII codes for 
carriage return, linefeed, etc. (Line printer mode only). 

If no filenames are given, boise reads its standard input 

Automatically run programs depending on which files are out-of-date. See Chapter 8. build 
is an extension of the Unix make program. 

File concatenation program. Copies each named file to the standard output A hyphen 
("-") represents standard input. If no arguments are given, standard input is assumed. 
There are no flags. 

Compiles C source programs for running on the m68000 processors. See the Unix man 
page. 

Change directory: change the current context Built in to the exec. 

Lets you play a game of checkers against the workstation. This is also a good 
demonstration of the VGTS's graphics capabilities. See Chapter 6. 

Kill off any exec whose standard input server or standard output server has died. 
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CI 

clear 
clock 

CO 

cp 



cpdir 



ex 
dale 

date 

debug 
debugvgts 

define 
delcorr 

delexec 
destroy 



diff 



Part of the Revision Control System. Described by a UNIX manual page. 

Clears the AVT. 

An analog clock. Understands two flags: -s (with second hand) and -t (without text, in case 
you want to zoom the clock). 

Part of the Revision Control System. Described by a UNIX manual page. 

If two filenames are given, cp copies the first file specified to the second file (or to stdout 
if the second filename is "-"). If more than two filenames are given, or the -d flag is 
given, the last argument is assumed to be a directory name, cp copies the first n-l files 
specified into that directory, forming the name of each new file by appending the last 
component of the corresponding old file to the directory name. Note that this behavior is 
not quite identical to that of the Unix cp program; the V cp program does not attempt to 
determine whether the last argument "is" a directory. 

Invoked as: 

cp d 1 P flags Jromdir todir 

copies all files in the jromdir directory to todir. todir must previously exist The -p flag 
specifies that the copy should be recursive: the entire subtree rooted at Jromdir is copied. 
The -y flag suppresses copying files if a destination file of the corresponding name already 
exists and is younger than the source file, i.e., has a more recent modified date. The -v flag 
causes a 'verbose' message to be printed each time a file is copied. 

Changes your current execution context— see section 3.6.9. This command is built into the 
exec. 

Distributed version of YALE (Yet Another Layout Editor). This is a VLSI layout editor 
that provides graphics editing of SILT chip descriptions. YALE is documented in a 
Stanford CSL Technical Report. 

Prints the date as maintained by the local workstation kernel, and as maintained by first 
responding network time server. The kernel-maintained time on a workstation is set from 
a time server when the workstation is booted. The command date -s resets the kernel- 
maintained time from a network time server. 

The V debugger. See Chapter 9. 

Allows the user to turn on/ofF debugging output from the VGTS. See section 46.5 for 
further details. 

Defines a local name (alias) for a context The first argument is the new name to be 
defined. The last argument is a context name, specifying the value to be given to the new 
name. Built in to the exec. 

Delete coixespondences from your V user identity to UNIX user accounts. Each V user 
can correspond to one account on each local UNIX machine that is running a V/UNIX 
server. The V superuser can delete correspondences for other users as well as itself. See 
Chapter 43 for more information about user correspondences. 

Delete an executive, specified by its exec id. The first exec created when the workstation is 
booted will always have an id of 0. 

Takes the name of a team (or any suffix) as an argument, and destroys the root process of 
that team. If the argument begins with the characters Ox, it is taken as a process id, and 
that process is destroyed. This is useful for killing processes run in the background. The 
-1 flag causes the process to be interrupted (with ForceException) instead of 
destroyed. 

This command has the same syntax and semantics as under Unix 4.2 BSD, with the 
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do 

domake 
dopar 



doseq 

draw 
echo 
fexecutc 

freemem 

gftodvi 

gftype 

grep 

hack 

ident 

instances 



intemetserver 
iphost 

killprog 
listdir 

listdesc 

login 

logout 

mail 



addition of the -n option of the Revision Control System's rdtf f program. 

Create an exec with a named file as its input. This file should contain a list of V 
commands, exactiy as you would type them, one to a line. If the -v option is given, then 
each command line is typed out at the time that it is executed. 

A synonym for doseq (described below). 

A program similar to doseq, except that it allows the executions of its command 

arguments to take place in parallel on different hosts. For each context, the program 

prompts for the name of a host on which to execute the command, and pops up an AVT 

that acts as the command's standard input and output If "any" is entered as the host 

name, then an arbitrary remote host will be selected. The local host can be selected by 

entering "(T. 

This program takes two string arguments: a list of context names, and a command to 

execute. The command is executed in each context in turn, doseq is often useful in 

buildfiles. 

An interactive drawing program that runs under the VGTS. See Chapter 10. 

Echos its arguments. The -n flag suppresses the newline at the end of the output 

Force a command to be executed on the server providing the current context, as described 

in section 3.4. 

Displays a bar graph showing the current percentage of free memory, and the percentage 

before the last change. 

For producing magnified proofs of fonts created by mf (a, v.). 

Produces terminal-readable output from a gf font file. See «f . 

This command has the same syntax and semantics as under Unix 4.2BSD. 

A rogue-like game. See chapter 11. 

Part of the Revision Control System. Described by a UNIX manual page. 

A diagnostic program that prints out information about any file instances (see chapter 33) 

that are being maintained by the server that is providing your current context At present 

this will work only if your current context is being provided by a Unix server (see chapter 

43). 

A version of the Internet Server. See chapter 39. 

If given a single host name as an argument iphost lists all IP addresses corresponding to 

that host If no argument is given, the IP address of the local workstation is printed. 

Kill the program, if any, running in the specified executive. 

Lists the names defined in one or more context directories. If the -1 flag is given, listdir 
prints one line of information about each object The output is sorted by default; the -n 
flag specifies "no sorting." If no argument is given, the current context is assumed. 

Prints one line of information about each named object extracted from its object 
descriptor. If no argument is given, the current context is assumed. 

Log in to the V system. See section 3.3.1. 

Log out of the V system. See section 3 32. . 

The UC Berkeley Unix 4.2 mail program, ported to the V-system. Note that this program 
is merely a front end (for composing, reading and editing mail). In order to use this 
program, your current context must be on a Unix system. The program's commands are 
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the same as in the Unix version, with the following exceptions: 

1. The ~e command invokes ved by default 

2. The new command "Quit" (or "Q" for short) behaves just like the "quit" (or "q") 
command, except that if new mail has arrived, you will be immediately put back in 
the "mail" program so that you can read it 

3. The new command "Update" (or "U") is like "Quit", except that you will be put 
back in "mail" even if no new mail has arrived. (This command is equivalent to 
exiting the program, and then re-running it) 

4. "raal 1 -c n n will cause the program to check your mail file, every V minutes, for 
the arrival of new mail. If new mail is found, the "Update" command described 
above will be run automatically (unless another command is in progress at the time). 

memserver A server that allows unused main memory to be used for temporary file storage. See 

section 40 for more details. 

mf Metafont-84 is Donald Knuth's language for compiling algebraic shape descriptions into 

bitmap images and fonts (m68k only). See Knuth's book The MetafoniBook (Addison- 
Wesley, 1986). Also note the programs gf todvl and gf type. 

migrateprog Migrate a guest program from the local machine to another machine Invoked as 
mlgrateprog [-p] [-h <host-name>] [<progs>] 

The unit of migration is the logical host not individual teams. All remotely executed 
programs are created in their own logical host whereas all locally executed programs are 
run in the system logical host which never migrates. Thus only remotely executed "guest" 
programs will ever migrate. Currently there is no way to create a locally invoked program 
in a separate logical host other than to invoke it remotely from another machine. 

If no arguments are specified then all guest programs on a machine are migrated to "lightly 
loaded" machines, where lightly loaded is defined in the same sense as any is defined 
when initially executing a program remotely. The -p flag specifies that information about 
what programs are being migrated where should be printed out The -h flag allows 
specification of a particular machine to migrate to. The machine to migrate to may be 
specified by either the hex pid of its team server (in the form Ox(pid)) or by giving its 
official string name (e.g. sun-mj416). If specific programs are specified then only those 
programs are migrated. Programs may be specified by the hex pid of one of their processes 
or by their full invocation name, as stored by the team server. 

mon This program monitors resource utilization of the workstation and presents it graphically. 

The -d flag specifies a vertical display ("down") instead of horizontal. The default display 
shows percentage used of memory and processor, and the number of incoming Ethernet 
packets per second. The flags -m, -p, and -e limit the display to only those specified. The 
-f flag violates the user interface standards by putting the display in the upper right corner 
of the workstation instead of requiring the user to position it with the mouse. 

name Prints the login name of the user under whose account the command is running. 

newterm Change terminal agents. Takes one argument the filename of a new terminal agent to take 

the place of the existing one. All executives running under the old terminal agent are 
destroyed; the new one will presumably provide means of creating a new one. For 
example, newterm sts replaces the VGTS with the Simple Terminal Server, which does no 
graphics but simply presents the workstation as an ascii terminal If no argument is given, 
it defaults to "vgts". 

Warning: If the named program is not in fact a terminal agent, you will probably lose control of your 
workstation. 
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pagemode Enable or disable paged output mode in the current executive. Takes one argument, which 

may have one of two values: "on" or "off". When paged output mode is on, the terminal 
agent stops writing to a AVT when the AVT fills up with output. The terminal agent then 
displays the message "Type <space> for next page" and waits for the user to issue a 
command which unblocks the AVT. The user interface for paged output mode is 
described in section 2.6. 

password Use this program to change your V password, home directory, or personal name. The V 

superuser can also use it to create new accounts or modify other users' accounts. Uses the 
fields package (section 21). To modify the displayed Name, Fname, or Home, click on 
the old value with the mouse, use the normal line-editor commands to change the value, 
then hit return. To make the change take effect, click on Modify and supply your old and 
new passwords. 

Other functions: click on find to find another user's authentication database entry. Click 
add to add a new user account (a unique user number is selected for you). Click delete to 
delete the displayed account Click exit to leave the program. 

pc68 Compiles Pascal source programs for running on the m68000 processors. See the Unix 

man page. The flags are similar to those of cc68. 

pwd Prints the absolute name of the current working directory. Built in to the exec. 

pwx Prints the (absolute) name of your current execution context— see section 3.63. This 

command is built into the exec. 

Q This is an experimental interactive functional programming language (m68k only). See Per 

Bothner (bothner@su-pescadero) for information and a user guide. 

query Prints out the result of performing various 'query' operations. In particular, query 

kernel prints the result of the QueryKernel ( ) library routine (see page 27-3), query 
conf 1g prints the contents of the workstation's configuration file (see Chapter 19), and 
query ethernet prints the result of querying the "ethernet" device (see section 36.1). 
query ? lists the possible options. 

queryexec Fmd out the status of the specified executive. Useful mainly for system testing. 

ranlib68 Identical to the UNIX rani 1b command, but handles archives of either m68k or vax 

binaries. This command is installed on UNIX under the name ranl1b68, and on V 
under both the names ran 1 1 b and ran 1 1 b68. 

res Part of the Revision Control System. Described by a UNIX manual page. 

rcsdiff Part of the Revision Control System. Described by a UNIX manual page. 

rcsmerge Part of the Revision Control System. Described by a UNIX manual page. Currently, this 

program must remotely execute the rdlff 3 and merge programs of RCS on a UNIX 
host, since the latter have not been ported to V. 

rename Renames the object specified by the first argument to the name given as the second 

argument Will not move objects from one server to another; there are also restrictions on 
moving objects within one server (for example, from one file system to another under the 
Unix server). 

rlog Part of the Revision Control System. Described by a UNIX manual page. 

rm Takes one or more filenames as arguments, and removes each file. The -f flag suppresses 

error messages if some of the files do not exist 

Note that in particular, rm may be used, as an alternative to the destroy command, to 
destroy one or more teams (by name). For example, 
rm [team/toto/[b1n]1nternetserver 
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sed 
serial 



show 



sleep 

sort 
startexec 



storagestats 
stuffboot 



tail 
talk 



will 'remove' (i.e. destroy) the program "fbinjinternetserver" that was executing on host 
"toto". Unlike the destroy command, the mil program name must be given. 

Stream editor. Described by a UNIX manual page. 

This program provides a full-duplex conversation between its standard input and output, 
and a device connected to one of the serial ports of the workstation. The argument is a 
device name, specifying the line to be opened. It defaults to fdeviceJserialO if omitted. 
Names of the form fdevicejserialn (with n a single digit) can be abbreviated by giving only 
the digit If the serial line is connected to a modem or a terminal port on another 
computer, this program allows the workstation to act as a terminal. The flag -b b 1 1 rata 
can be used to specify the bit rate (baud rate) of the connection; it defaults to 9600 bps. 

Displays a .dv1 file or a .press file. It creates a menu in the invoking window; 
commands are normally selected with the mouse. A new window is created for displaying a 
page from the . dv1 or .press file. You can invoke the program with show filename, or 
you can set the filename in the menu. More details are given by the "help" command 
(type h or select [Help] with the mouse). TeX generated dv1 files are handled pretty 
well, except for possibly missing fonts (and perhaps speed). The press support is pretty 
minimal 

Delays for a time, then exits. The delay time (in seconds) must be specified as an 
argument. 

This command has the same syntax and semantics as under Unix 4 2BSD. 

Create an exec in a new AVT. The new exec will have the same context as the exec from 
which startexec was invoked, not the [home] context For most purposes the view 
manager's Create Executive commands are to be preferred over this one, as the view 
manager will not work on an executive created by startexec. startexec prints out 
the exec id and process id of the new exec. 

Obtains access statistics collected by the V storage server and disk driver. The -c flag 
causes the statistics to be cleared to zero. 

A program that stuffs the file named in argument 2 into the boot block of the disk named 
as argument 1. The file to be stuffed normally will be Vload and is needed during auto- 
boot when the boot program is read out of the boot block on the root disk device. If a third 
argument is present, it is taken as the name of a file to copy into block #0 of the root 
device (the disk label). 

This command has the same syntax and semantics as under Unix 4.2BSD. 

Allows interworkstation communication among V hosts similar to talk under Unix. 
Invoked as 

talk [person] 

Person is optional. If person is specified, it can either be in the form userld to specify a 
user on the first host we find that user to be logged in, user1d6host to specify a 
particular user on a particular host, or Qhost to get anyone on that host 

Once inside talk, you can enter commands by first typing (Esq, and then another letter. 
The available commands are: 

i invite a new user. You are prompted for who you want to invite, and 

you can respond in any of the ways mentioned for person above. 

1 log in AVT. This allows you to see in a temporal fashion who says what 

You are prompted for a new AVT to write the log in. Giving this 
command again terminates logging. 
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q quit Only you quit; any other persons engaged in the conversation can 

continue to do so, even if you were the one who initiated the 
conversation. 

r read from file. It reads the file into the conversation such that it looks as 

though you typed it all. However, there is currently no pagenation. If 
what was read is very long it will quickly get overwritten. 

w write to file. This is the same as "log in AVT above, except logging is 

done to a file you specify. Giving this command again terminates 
writing. 

Warring: tal k runs only under the VGTS. There is currently a compiled in maximum of six talkers 
in one conversation, tal k AVTs are fixed at 24 by 80. 

Due to current VGTS restrictions, tal k is forced to initiate a conversation by writing to the VGTS 
AVT (the small one originally in the lower right hand comer) and then opening a new AVT, which 
gives the victim a pad cursor. To accept the invitation the AVT is placed normally: to reject the 
invitation dick all three mouse buttons. This is bad if the VGTS AVT is obscured- the victim will 
get a beep and a AVT prompt and not know why. 

telnet IP/TCP-based telnet implementation. It can run under the STS, or in a VGTS AVT. A 

destination host name or address may be given as a command argument; if none is given, 
telnet prompts for one. A host name is a string of non-white-space characters starting with 
a non-numeric character. A host address is a string of the form a.b.c.d, where a,b,c and d 
are decimal integers. Both names and addresses may be followed by a dot and a decimal 
port number (with no intervening spaces). 

If the -e flag is given when it is invoked, telnet recognizes a set of commands prefixed by 
ctrl-t while connected to a remote host Ctrl-t ? prints a list of all such commands. These 
functions are not available by default because they sometimes interfere with higher level 
protocols such as that used by the VGTS. 

After disconnecting from a remote host, telnet prompts for another host To exit telnet, 
enter ctri-c or ctrl-z in response to the prompt 

If there is no internet server on your workstation when telnet is loaded, it runs one in the 
background. The -1 flag inhibits loading a local server, instead looking for a public internet 
server running on another V host 

The *d flag enables debug mode. In this mode, all transmitted and received telnet protocol 
commands are printed, and all received non-printable characters are printed in an escaped 
notation. Debug mode can be toggled on and off by typing ctrl-t d while connected to a 
remote host if the -e option is specified on the command line. 

The -g flag enables logging mode, which implies the -d debug mode above. A file, 
"telnetloigfile" will be created in the current directory. This file will contain a complete 
transcript of bothe sides of the telnet session. Lines preceded by "<" originated from the 
host while those preceded by ">" originated from the workstation. All non-printing 
characters are quoted and all telnet protcol commands are printed. Password input is 
automatically deleted. This mode is transparent to both sides of the connection. Logging 
mode can be toggled on and off by typing ctrl-t g while connected to a remote host if the -e 
option is specified on the command line. 

telnetserver IP/TCP telnet listener. This program listens for incoming telnet connections on the local 

internetserver, spawning a remote terminal server (RTS) for each connection received. 

testexcept Simple interactive program for testing the exception server. 

timeipc Performs timing tests of the V interprocess communication primitives. See chapter 13. 

timekernel Program to measure the time for Send/Receive/Reply kernel primitives. 
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tsort 
type 

undefine 
ved 

vemacs 

w 
wc 

wh 
whi 



Topological sort Identical to the UNIX program of the same name. 

Type out one or more files on the terminal. Types a page-full and then stops and waits for 
input. Pressing [SPACE] brings up another page, while [RETURN] brings up another line. 
Hit q or tC to quit. 

Removes the definitions of one or more local context names (aliases). Built in to the exec. 

A text editor, somewhat similar to Emacs, that runs under the VGTS. Described in 
Chapter 14. 

A version of the Emacs text editor that can, among other things, make use of the window 
features of the VGTS. When vemacs is invoked without any arguments, it will display a 
help file describing how vemacs differs from standard Emacs. 

Lists logged-in V users throughout the network. 

Counts characters, words, and lines in a text file. See the UNIX manual for full 
documentation. 

Lists hosts on the network together with information such as logical host name, free 
memory, average processor usage, number of free process descriptors, host type, etc., 
sorted by host name. 

Lists currently executing teams for each host If one or more 'host' arguments are given, 
then only the teams on the specified host(s) are listed. Such arguments can take the 
following form: a hostname, a pid (Ox . . . ), or "0" (indicating the local host). 



4.2. Commands on Non-V Hosts 

There are also several useful commands that can be invoked on non-V hosts (usually a Vax/Unix system). 
Use these commands once you have logged into a machine through a telnet connection. Most of these 
commands also have versions that run locally on the workstation under the VGTS, and the Unix versions can 
also be run remotely under the VGTS, using the exec's remote execution feature (section 3.4). 

dale 

draw 

photo 

siledit 



silpress 



A version of the Yale layout editor that runs under the VGTS. 

An interactive drawing program that runs under the VGTS. See Chapter 10. 

Reads and displays a ".sun" format raster file. 

A program which edits .SIL format files. SIL, a Simple Interactive Layout program, is a 
graphics editor for logic designs and illustrations. 

A program which takes a .sil format file and produces a .press format file that can be 
printed on the Dover. 
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Amaze is a game for two to five players which runs under the STS on a workstation with a framebuffer. If 
you see the letters VGTS in a small window on your screen you arc not running the STS. See section 2.2 for 
instructions on how to start up the STS. 

To run amaze, type the command 
amaze 

If no one else is playing, it will type "New game starting" and then draw the maze. Otherwise it responds 
with "Joining game as player number x" and then draws the maze. Your player token, called a monster, will 
be sitting in the center of the screen just above a checkered flashing door. From this point, you control your 
monster through the keyboard. The commands are: 

1 Move the monster up. 

Move the monster down, 
j Move the monster left. 
1 Move the monster right, 
k Hold the monster at its current position, 
a Let the monster's moves be selected randomly. 

e Fire the monster's missile up. 
c Fire the monster's missile down, 
s Fire the monster's missile left, 
f Fire the monster's missile right. 

(Note: the missile can be fired only once every six 
seconds. ) 

h Hide the monster from other players — no shooting allowed 

while hidden, 
v Let the monster be seen again -- can shoot again, too. 
(Note: monsters stay hidden for ten seconds, but once 

they become visible, they remain visible for 16 seconds.) 

Set monster velocity to 0. 

1 Set monster velocity to 1. 

2 Set monster velocity to 2. 

3 Set monster velocity to 3 — the starting velocity. 

4 Set monster velocity to 4. 

5 Set monster velocity to 5. 

q Quit the game, but continue to watch other players, 
t Rejoin the game just above the door, 
r Rejoin the game at a random corner in the maze. 
Ctrl-C Terminate your involvement with the game. 

R Redraw the maze and players. 

Note that to leave the game entirely you hold down the CTRL key and type *c\ 
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5.2 amaze: A Maze Game 



To rejoin the game after being shot by another monster, use either the t or the r command. The game 
currently docs not keep score of the number of hits you inflict or suffer. 

Problems and questions should be directed to Eric Bcrglund. 
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checkers allows you to play a game of checkers against the computer. The default version of the program 

executes entirely on the players workstation. 

• 

On starting the program, the view manager will prompt you for the position of the SGVT representing the 
checkerboard. 

The player moves the 'red' (white) pieces; the program's pieces are black. You are expected to make the 
first move. You can, however, force the program to move first by "passing". (Sec the paragraph describing the 
menu, to follow.) To make a move, move the mouse to the square containing the piece that you wish to move, 
and click either the left or the middle mouse button. If this piece can be legally moved, it will then be 
highlighted. Complete the move by moving the mouse to the destination square and once again clicking the 
left or the middle button. 

If the move that you have selected is legal, your piece will be moved, and the program will then make its 
move. Note that having selected a piece to move, you can abort this selection by clicking an illegal destination 
square (the source square itself, for example). If a capture of an opposing (ie. black) piece is possible, your 
next move must be a capture. A message indicating such "forced captures" will be displayed just below the 
board. In such a case, the program will not allow you to make a move that is not a capture. Multiple captures 
are handled correctly - if you move a piece by making a capture, your move will not be completed until all 
possible captures with this piece have been made. 

The standard rules of checkers apply. If a piece reaches the eighth rank of the board, it is promoted to a 
king; kings may move in any direction. A side wins either by capturing all of the opposing pieces, or if the 
opposing side can make no legal move. 

When it is your turn to move, you may also use the right mouse button to select from a menu of options, 
which arc described below: 

Redraw This causes the VGTS to redraw the entire board. This command should rarely be 

necessary. 

Pass (skip turn) This command can be used if you want the program to make the first move. You can also 
use this to avoid any capturing obligations. 

Change search depth 

By default, the program searches 4 half-moves ahead when choosing its next move. That is, 
it considers its own move, your response to this move, its next move, and your response to 
that The "Change search depth" command allows you to change the depth of lookahcad 
to any value from 1 to 8. Don't select any of the higher depths unless you have a lot of 
patience, however. '11k program takes about 20s to respond to a typical opening move 
when the depth is 6, about 50s when the depth is 7, and about 3 minutes when die depth is 
8. (These times were taken on a 10 MHz SMI workstation - Cadlincs will be slightly 
slower.) Note that you may find out the current search depth by selecting "Change search 
depth", and then clicking outside the 'depth' menu. 

Edit board This command puts you into Edit mode, which allows you to cheat by adding pieces to, or 

removing pieces from, the board. Edit mode is described below. 

Back up one movcThis allows you to retract (eg. to correct) your last move. 

Resign The quick and cowardly way to end the game. 
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The program chooses it's move by performing a 'brute-force' search, using alpha-beta pruning. It evaluates 
the board positions at the 'leaves' of the search tree using a simple heuristic based on the number and position 
of pieces on each side. A 'value indicator' to the right of the board indicates the value of the current position; 
as seen by the program. (If the indicator is above the halfway mark, for example, then the program 'believes* 
that you are winning.) There are also counters immediately above and below the value indicator, giving the 
number of pieces on each side. The value indicator and the piece counters arc updated whenever the program 
completes its move. 

You can make changes to the board (between moves) in Edit mode. In this mode, a special menu is 
displayed to the right of the board. To add a piece to the board (or change an existing piece), click the square 
in the menu that contains that piece. You may place a copy of this piece on any (shaded) square of the board, 
by clicking that square. You may do this repeatedly; it is not necessary to select from the menu each time. 
Note that you use the 'empty square' to delete one or more pieces from the board. You may remove all pieces 
from the board by clicking "Clear". When you have finished making changes to the board, click "Done" to 
leave Edit mode, it will still be your turn to move next 

. .'IS 

A distributed version of the game may be started by specifying the r flag: checkers -r <NoOfSla\es>. The 
program will then try to create up to NoOjSlaves slave processes on lightly loaded remote workstations, that 
help in the search of the alpha-beta search tree. As far as the player in concerned, the only two noticeable 
differences to the default sequential version of the game, arc the possible improved response times and that 
the computers moves may be nondetcrministic. (Note: it is only worthwhile to play the distributed version of 
the game if the search depth is chosen greater than four.) 

Mail comments and/or gripes to stumm@pescadero. 
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bits: a bitmap and font editor 



bits is a special-purpose editor for working with bitmaps and fonts. It makes intensive use of the VGTS. 
The virtual terminal qf the executive under which bits is started up, is used to display various status 
information, as well as being the menu of commands to execute. When started, bits will ask for you to 
create a new view (of a new virtual terminal) in which the actual editing is performed. If you request to view 
sample text, you will be asked to create a third virtual terminal (see below). These last two virtual terminate 
are SGVTs and can be zoomed. 

(Note: If you are using a Sun-120 framebuffer (including a model 50), you should read the Bugs section!) 

7.1 . Command Input 

In this chapter, when you arc asked to do the command [xxx], it means that you should select and click 
the mouse at the field [xxx] of the status/command virtual terminal. You get the same feedback as with 
pop-up menus, with the field in inverse video. Some of these fields, when activated, expect you to type in 
some number or string. In those cases, you have the full power of the line editor, until you type a <rcturn>. r 
(To abort input, type CTRL-g.) 

7.2. Rasters 

The important thing to remember is that b1 ts handles pointers to bitmaps. These we call rasters. A raster 
also contains size and offset data, so it can point to part of a bitmap. You can name a raster using the [Store, 
with new name] command, and later retrieve it from the Table of saved rasters. You can thus 
save multiple pointers to the same bitmaps under different names. If you change bits in one of the bitmaps, 
the bits will also change in the other rasters, since they refer to the same bitmaps. Use the [Save a fresh 
copy] command to make a virgin copy of a bitmap, which is guaranteed to have no other rasters pointing at 
it. ' ;i ■ 

7.3. Changing Raster Size 

To change the size of a raster, point at the boundary, hold down the middle button and "drag" the boundary 
to where you want it. You can also change the size of a raster with the [W1 dth] and [Height] commands*! 
To do this, select one of these fields, and type in a number. ITic absolute value typed in becomes the new 
size. If the value is positive, the old and new rasters coincide at the top left corner; if the value is negative, 
they coincide at the bottom right corner. 

Note that when you change a raster's size, all other rasters pointing at the same bitmap will be adjusted to 
point at whatever bits they used to point at. This is true even when you increase the size. (When the size is 
increased, and the underlying bitmap is larger than the part pointed to by the current raster, the hidden part, 
of the bitmap will appear. If this isn't enough, a new bitmap will be allocated, and all the pointers adjusted.).,^ 
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7.4. Bitmap I/O 

You can read and write bitmaps in .sun format (as used by the photo program), using the [Read 
paster] and [Write raster] commands. To write a raw raster in hex suitable for putting in a C 
program, use the [Wr 1 te hex ] command. 

7.5. Painting 

To set (blacken) a pixel, point at it with the mouse, and click the left button. To clear (whiten) a pixel in a 
bitmap, use the middle button. 

7.6. Inverting a Raster 

Selecting [Invert black and white] inverts the interpretation of black and white pixels. This 
interpretation is actually stored as part of the raster object, so no pixels are actually changed (except on the 
display). 

7.7. Raster Operations (BitBIt) 

You can do a general 2-operand BitBIt with the [Raster operation] command. The current 
(displayed) raster is used as one of the operands (the "destination"), so this should be selected first Then give 
the [Raster operation] command, after which you will be asked to select an operation. Available are 
plain copy, 'and', 'or' (paint) and 'xor\ In addition, the [Invert Source] modifier first inverts the source. 
[Invert Destination] docs the same for the destination, which means inverting the destination 
operand and the output result Finally, you must select the other operand (the "source") from the name table. 

You can also select [Get the empty raster] as a source. This gives you an infinite plane of white 
pixels. This, together with the [Invert Source] option, allows you to conveniently clear or set any 
rectangle. 

7.8. Reflection and Rotation 

Selecting [Reflect/Rotate] will do one of these transformations. (A popup menu asks for the 
particular transformation.) Note that the result is a "fresh" raster: There arc no other rasters or tables 
pointing at its bitmap. 

7.9. [Replace in table] 

This command asks you to select an clement in the raster table or the current font The clement is replaced 
by the current raster. If a [Table of saved raster] clement is replaced by the Empty Raster, its space 
is freed. 

7.10. Making a Copy of the Screen - CURRENTLY NON-WORKING 

You can make copy of the frame buffer, with a little bother. Select [Get f ramebuf f er], which gets a 
pointer to the frame-buffer. You should now use [Height] and [Width] to reduce the time and space 
required to deal with it. (The framebuffer is big.) You should [Save a fresh copy] to sec what's going 
on, and then use the middle button to select the part that interests you. 'Iliis will be slow, since such a big 
raster is involved, and you will also have to use die VG'I'S workstation manager commands. 
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7.11. Fonts 

A font is a collection of characters. From bits' perspective, a character is a bitmap with some extra 
information. b1 ts currently knows about fonts in the following formats: 

• sf format ("Sun format"), which is specially optimized for the Sun-1 graphics hardware. (Will soon be 
obsolete.) 

• The same format, but the font is stored in an archive (library) of relocatable binary files. Thus fonts can 
be linked in with programs, or read in at run time. The standard fonts are stored in 
/usr7sun/11b/11bsfonts.a. 

• Pxl format, which can be generated by MetaFont78, and is used by a lot of the TcX people. 

• Gf ("generic font") format, a compact format generated by MetaFont84. 

To read / write a font, select the desired field in the Read font | Wr 1 te font table. Note that you 
cannot write a font to an archive. 

7.11.1. Displaying Fonts 

When a character in a font is displayed, there are runny lines sticking out of the bitmap picture. The 
intersection of the left and top segments indicates the origin of the character: The left segment indicates the 
baseline, and the top segment the starting position. The intersection of the right and bottom segments show 
the "ending position": the vector from the origin to the ending position is the width of the character. The 
width vector is almost always horizontal, and indicates the spacing between adjacent characters: The "next" 
character in a string should be positioned so that its origin coincides with the ending position of the current- 
character. 

You can select any of these lines (with the middle button), and adjust them with the mouse. 

7.11.2. Font parameter* 

This is a section of the AVT with magic numbers about the current font. They can all be changed, but you 
should know what you arc doing. 

Design size is the size in points at which the font is designed for. Resolution is ratio of pixels per 
point (vertically and horizontally) at which the font is designed for. (To be compatible with the Altos, we 
have decided that die resolution of the Sun display should be defined to be 80 pixels/inch. Older Pxl fonts 
use a magnification relative to a default Pxl resolution of 200 pixels/inch.) Both these arc TcX/Pxl 
parameters. 

[Raster al ignment] is the bit boundary character bitmaps should be aligned on in sf font files. It 
must be 1, 8, or 16. 

[Max . height] and [descent] give the maximum total height, and descent below the baseline, of all 
the characters in the current font. If you change [descent], the baseline of all the characters will be 
adjusted accordingly. 

7.12. Sample Texts 

To study how a text string would look at no magnification, select [Sampl e text]. You should then type 
in the text you want displayed. This text will be placed in a new virtual terminal. To change the text, just 
rcsclcct [Sample text]: the old text will be placed in the line editor buffer, to simplify small changes. If 
you edit die font, select [Redraw] to update the sample. 

Note that in the sample, the character * \ ' is special, (t is used to indicate special non-ascii characters, as in 
C. Specifically, • \ ' followed by a 3-digit octal number is the character with that ordinal value. \\ displays \, 
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and \b, \t, \e, \r and \n arc Backspace, Horizontal Tab, Escape, Carriage Return and Line Feed, 
respectively. \0, \A, ... \_ are control characters: tQ, tA, ... t_, 

7.13. Printing a Raster 

There is a Unix program to convert a . sun file to a . press file. To run it (on some Stanford VAXen), do: 
/usr/sun/src/graph1cs/p1x/sunpress -p X. press X.sun 
This, together with the (non-working) [Get f ramebuf f er] command, allows you to print a hardcopy of 
the screen on a Dover printer. 

7.14. Bugs and Problems 

. sun files use 1 to mean 'white' while bits uses 0. This means that you should [Invert black and 
white] after reading and before writing, if you want to use the bitmaps for programs like sunpress and 
photo. 

The are some limitations on how bitmaps arc displayed by the VGTS. A bitmap can only be magnified 1, 2, 
4, 8, or 16 times, so other zoom factors will be wrong. Also, it is over-conservative when clipping rasters, 
which means that a whole row of bits could be missing. On Suns with the 120 frame-buffer, bitmaps cannot 
yet be magnified at all. BUT b1 ts still starts up with the working window magnified 8 times! 

Raster operations do not take into account that rasters may be overlapping. 

bits is not very robust against things like running out of memory. Caution would imply that you save 
your work often. 

The whole mechanism for grabbing a copy of (part of) the frame-buffer is very unclean (and currendy 
doesn't work). It should be done by the VGTS, not application programs. 
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build is an enhanced version of Fcldman's make program for Unix. It runs both under V and 4.2bsd 
Unix. 

Except in pathological cases, build is meant to be backward-compatible with make. Sec the Unix 
man-page for make. In this chapter, we describe only differences between build and make. 

build reads in a file describing dependencies. By default it looks for the files bu 1 1 df 1 1 e, makef 1 1 e or 
Makef 1 1 e (in that order) in the current directory. 

8.1. Macros 

A dependency file can contain lines of the form: 
0BJECTS«f1lel.b file2.b 
. This defines OBJECTS as a macro name, which can be used as in: 
cc68 -r -vV $(0BJECTS) 

Macro names can also be defined in the command tine: 
build M -D0BJECTS»f1lel.b f11e2.b" 
or cquivalcndy: 

build "0BJECTS=f1lel.b f1le2.b" 

8.2. Including other dependency files 

A line of the form 

^include filename 

will parse die filename when reading dependency rules. (The filename may optionally be surrounded by 
<. . .>or"... .",) 

The filename is resolved relative to the directory containing the currcntly-bcing-rcad file (the one 
containing the #1 ncl ude), not the current working directory. ' 

8.3. Conditional dependency rules 

rtMfdef name 
dMfndef name 
#else 
#end1f 

These act like C preprocessor directives. For example #1 f def X succeeds iff the macro X is defined. 
NOTE: If there is white space after a '#'-sign, the line is taken as a comment! 
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8.4. Search paths 

A line of the form 

VPATH-../68k ../ml 

or, cquivalently, 

VPATH»../68k:../m1 
causes build to search for files first in the current directory, then in the directory . ./68k and finally in 
. . /ml. The first form is probably preferable as the VPATH macro may then also be used elsewhere in the 
buildfile for other purposes. 

One use of this is for maintaining libraries for multiple machines, where most of the sources are in a 
machine-dependent directory . ./ml, but some of the sources and all of the binaries are in the current 
directory. 

Another use is for program maintenance: The sources being worked on can be in a private directory, while 
the remainder can stay in the master directory, if you put the master directory on the search path. 

NOTE: After macro-substituting command lines, bull d will look for words (i.e. strings between spaces). If 
there exists an alias for a word and the file is up-to-date, it will be replaced by the alias. An alias exists for a 
word, if build has searched for the file with that name, failed in the current directory, but found it on the 
search path. 

This simple-minded algorithm will usually do the right thing, but in pathological cases it might lose. 

8.5. Dependency patterns 

In addition to the old way of expressing dependencies using file suffixes: ' 

.SUFFIXES: .c .b 
.c.b: 

cc68 -c $*.c 

you can also use more general pattern-matching: 

*.b: $«.c 

cc68 -c $*.c 

That is: a rule for making files can have as its target a pattern containing at most one **\ The part of the file 
name matching the '*' defines the value of $*. 

8.6. Suggestion 

If there are many files, you can speed up build (quite significantly for the V version at least) by starting out 
with a empty .SUFFIXES: line, and explicitly defining just the suffixes you need. This saves build from 
having to check for the existence of .y files etc. 

8.7. Bugs 

Docs not understand RCS. 
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9.1. Synopsis 

debug [-d] [-o origin] progName progArgl progArg2 ... 

9.2. Description 

9.2.1 . Invoking the Debugger With a Program 

Debug is an assembler-level symbolic debugger for V programs. Versions exist for both the Vax and the 
68000. 

It can be called as a command to the V exec and takes the following arguments: 

-d If the VGTS is available, then this argument causes an AVT to be created for the debugger 

which is separate from the one used by the program to be debugged. This option is a 
necessity for programs which read- keyboard input via separate reader processes since these 
may interfere with the debugger's keyboard input requests. 

-o origin The origin is the location where the program to be debugged was linked to load (c.g M 1000 

or 2000 in the case of the kernel). The default value is the normal team origin (currently 
20000). This option is usually only used by kernel hackers in place of getting a symbol 
table dump and assembler listing when debugging. They issue the command debug -o 
2000 /xV/kernel/sun2+ec/sun2+ec (for example), and can find out exactly what 
is at the address where it crashed. The debugger disables the g, x, etc. commands when in 
this mode. 

progName The name of the program to be debugged. 

progArg/i The nth argument of the program to be debugged. 

Thus, to debug a program which is normally invoked by: 

progName argl airg2 
one types 

debug progName argl arg2 
If a separate AVT is desired {for VGTS resident environments only) then one would type 

debug -d progName argl arg2 

9.2.2. Postmortem Debugger 

The debugger can also be used as a "postmortem" debugger. The V team server is structured so that if an 
exception occurs in the program currently being run, the debugger is automatically loaded and given control. 
The postmortem debugger is always run with the -d flag. 
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9.2.3. Common Usage 

A program invoked with the debugger will start out at the debugger's command level. Breakpoints may be 
set and the program code and global variables may be examined. The program can then be started using the 
commands described below. 

A frequent "postmortem" use of the debugger is to obtain a stack trace to find out where a program 
incurred an exception and then quit This is done by typing s after having been transferred into the 
postmortem debugger to get a stack trace, and q to quit: 
I oroq arol ara2 

Bus error on read from address f 1n process 2ed0024 

Instruction Program Counter Status Register/PSL 

1010 10172 10 

B0> 10174 4880 ma1n+2C extw dO 

stack trace 

1 

9.3. Commands 

The debugger begins by displaying the line of code at which execution has paused, and then gives a period 
(7) as a prompt The user can then enter commands using the keyboard. Most commands are terminated 
with a carriage return: exceptions will be noted in the command descriptions. The only characters that may 
be used to erase previously typed input arc backspace (\b) and delete (DEL). The entire line may be erased 
by typing CTRL-u. When omitting optional arguments in commands which take more than one argument, 
be sure to include the correct number of commas for the command. In this way the debugger can determine 
which argument is to be assumed. 

9.3.1. Definitions 

Within the command descriptions below, an expression is some combination of numeric constants, register 
symbols, globally visible symbols from the program being debugged, and the operators +, -. and |, 
representing 2's complement addition, subtraction, and bitwise inclusive or, respectively. Blanks arc not 
significant except in strings. All operations arc carried out using 32-bit arithmetic and evaluated strictly left to 
right 

Register symbols arc symbols which represent the various processor registers. The following symbols are 
recognized on the 68000: 
%d0 - %d7 Data registers 0-7. 

%a0-%a7 Address registers - 7. 

%fp Frame pointer (synonym for %a6). 

%sp Stack pointer (synonym for %a7). 

%pc Program counter. 

%sr Status register. 

The following symbols arc recognized on the Micro VAX: 
%r0 - %rl 1 General registers 0-11. 

%ap General register 12 (argument pointer). 

%fp General register 13 (frame pointer). 
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%Sp 
%pc 
%psl' 
%psw 



General register 14 (stack pointer). » 
General register 15 (program counter). 
Program status longword. ~ 
Program status word. 



In all commands except the replace-registcr (rr) command a register symbol represents the contents of the 
specified register. In the replace-registcr command it represents the address of the register specified. 

Globally visible program symbols are names of program routines or global program variables. Note that 
the VAX C compiler p t repends an underscore to the names of all global symbols. The debugger attempts to 
guess the correct symbol if no underscore is typed by the user, but it docs get confused sometimes. 

The single character 7 (dot) is treated as a symbol representing the last memory location examined. Its 
value upon entrance to the command level of the debugger is set to the current value of the program counter.. 

9.3.2. Execution Control Commands 

expression, number, b 

Set breakpoint number (in the range 2-15 decimal) at expression, expression must be a tegal 
instruction address. If number is omitted the first unused breakpoint number is used. If 
expression is the named breakpoint is cleared, or if number is omitted then all breakpoints 
are cleared. If expression is omitted all breakpoints arc printed. Note: if expression is 
omitted then number must also be omitted or must be preceded by a comma in order 
distinguish it from being interpreted as the expression argument 

VAX note (not applicable to the 68000): The VAX C compiler uses the calls instruction for all function calls! 
This instruction expects to find a 2-bytc register mask at the address specified and actually 
transfers control to that address plus 2. Therefore you have to add 2 to the address when 
setting breakpoints at functions in a C program on a VAX. This may or may not apply to 
subroutine calls in assembly language or in code generated by other compilers, depending 
on which instruction is used. 

expression, g Go. Start or resume execution at expression. If expression is omitted, then start execution 
at the current pc value. 

expression, gb Go past breakpoint. Like go with no argument, except that if we arc presently stopped at a 
breakpoint, then expression counts the number of times to pass this breakpoint before 
breaking, if expression is omitted, then 1 is assumed. 

expression* x Execute the next expression instructions, starting from the current pc and printing out all 
executed instructions. If expression is omitted, then I is assumed. Note: traps arc executed 
as single instructions; i.e. the instructions executed in a trap routine arc not displayed or 
counted. 

expression, y Same as x except that subroutine calls arc executed as single instructions; i.e. do not 
descend into the called subroutine. Note that breakpoints within the subroutines arc 
ignored. 

xx xx is a synonym for y 

; A synonym for x, except that each instruction executed is displayed on the same line as the 

command, providing a more compact display. No carriage return is needed to terminate 
this command; the semi-colon triggers execution. 

: A synonym for y, except that each instruction executed is displayed on the same line as the 

command, providing a more compact display. No carriage return is needed to terminate 
this command; the colon triggers execution. 
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The typcout mode referred to in the command descriptions is described under the t command. 

sp Toggle the flag that determines whether the whole team stops at an exception or just the 

process that incurred the exception. The debugger's default behavior is to stop the whole 
team when an exception occurs, not allowing any of its processes to proceed until one of 
the above Execution Commands restarts the team. (Of course, at that point ANY of the 
processes could resume execution -i.e., single-stepping one process could allow another to 
execute indefinitely.) If this command is typed, an exception in any one process will not 
halt any of the other processes on the team. Typing sp again makes the debugger go back 
to its original behavior. 

q Quit Exits the debugger and kills both the debugger and the program being debugged. 

9.3.3. Display Commands 

The following commands are executed immediately without waiting for a carriage-return (CR) to be typed, 
and their output overwrites the current line. (This provides a more compact display format.) 

expression/ 

expression\ Display the contents of expression. The typcout mode used is determined from the 

program symbol table and the current typcout mode. The value of dot is set to expression. 
The \ command is not very useful in instruction-typeout mode on the VAX (i.e. after 
giving the "T,tt" command) because the VAX uses variable length instructions and almost 
every byte value is a valid op-code, thus making it impossible to tell where the previous 
instruction really starts. Similar problems occur less frequently on the 68000. 

/ ■■■••■•■ * lN 

\ Display the contents of dot after having respectively incremented (/) or decremented (\) it 

The typeout mode used is determined from the program symbol table and the current 
typcout mode. 

@ 

expression® Display the contents of the memory locations pointed to by the value of dot or expression, 
respectively. ITic typcout mode used is determined from the program symbol table and 
the current typcout mode. ITic value of dot is set to the address of the memory location 
just displayed. Note that %pc will yield the contents of the memory location pointed to by 
the pc register (i.c. the current instruction) and that %pc@> will attempt to place an 
.,,. additional indirection on that memory location. %pc@ is almost always an invalid 

reference. 

expression^ Display the value of dot or expression, respectively. 

The following display commands arc executed when a carriage- return is typed. 

d Display the contents of all the registers. 

expressions Print out a stack trace describing die chain of subroutine calls and their parameters, to a 

maximum of expression calls, (expression defaults to infinity.) Warning: the debugger's 
stack trace examines the values of parameters as they currently exist on the stack, not as 
they were when the routine was called. Routines which change the values of their 
parameters will similarly affect the stack trace output 

expression, numlines, n 

Display the next numlincs memory locations, starting at expression. If expression is 
omitted, then display starts at dot If numlincs is omitted, then 24 lines arc displayed. 

expression, numlines,p 
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Display the previous numlines memory locations, starting at expression. If expression is 
omitted, then display starts at dot If numlines is omitted, then 24 lines are displayed. 

type, t Temporarily set typeout mode to type where type is one ofi 

V type out bytes as ascii characters. 

*h* type out bytes in current output radix. 

V type out words (2-bytes) in current output radix. 

T type out longs (4-bytes) in current output radix. 

Y, sirLength type out strings. Set the maximum length of strings to be strLength. 
The maximum string length determines how far the debugger is willing 
to look for the end of a string, which is assumed to be a '\0' byte. For 
programming languages such as Pascal which don't terminate their 
strings with a '\0' byte this limit is important to prevent endless string 
searches. The string maximum length is sticky (i.e. It need be set to the 
desired value only once). The default value is 80. 

T type out as symbolic assembler instructions. 

Note that the type characters must be surrounded by single quotes. If no argument is 
supplied then the default typeout mode is used. This mode tries to set the typeout mode 
based on the type of symbol(s) being displayed and uses T format when the mode is not 
obvious. The new typeout mode stays in effect until execution is resumed with one of the 
Execution Control Commands. 



type, tt 



Execution Control Commands. 

Permanently set typeout mode to type. The typeout mode is set to the default typeout 
mode if type is omitted. 

base, ir Set the input radix to base. If base is illegal (less than 2 or greater than 25, decimal) or 

omitted, then hexadecimal is assumed. (This is the default radix.) 

base, or Set the output radix to base. If base is illegal (less than 2 or greater than 25, decimal) or 

omitted, then hexadecimal is assumed. (This is the default radix.) 

offset, of Set the maximum offset from a symbol to offset. If offset is illegal (less than 1) or omitted, 

then hexadecimal 1000 is assumed. (This is the default offset) This command is useful 
when examining areas of the team, such as the stack, which arc more accurately labeled by 
hex addresses than by symbol + offset notation. 

charcount, si Set the maximum number of characters in a symbol which will be displayed to charcount, 
Ucharcount is illegal (less than 1 or greater than 128) or omitted, then 16 is assumed. 

9.3.4. Tracing Commands 

expression,* Watch the memory location at expression. When program execution resumes, the 
debugger regains control after every instruction and checks whether the contents of the 
location have changed. If so, a message is printed and the user gets control. Otherwise, the 
program continues. This causes the program to run several hundred times slower than 
normal. If expression is 0, watching is turned off. 

expression, vib Watch the memory location at expression, but only at breakpoints. A breakpoint will not 
stop the program if the watched location is unchanged. 

w Print information about watched location. 
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9.3.5. Replacement and Search Commands 

expression!, expression^ type, r .•_•■<*'■ 

Replace the contents of the memory location specified by expression! with expression!, 
expression is interpreted to have type type. Note: It is not currently possible to replace 
strings with this command, and instructions should be specified in 16-bit quantities and 
replaced with type T. If expression! is omitted, then the value is used. 

register, expression, n . 

Replace the contents of the specified register with expression. If expression is omitted, then 
the value is used, expression is interpreted to be a 32-bit quantity. 

expression, lowlimit, highlimit, type, f "*"* . 

Search for (find) pattern in the range lowlimit (inclusive) to highlimit (exclusive). 
expression is interpreted as an object of type type. Objects are assumed to be aligned on 
word (2-byte) boundaries except for 1-bytc types and strings, which arc aligned on byte 
boundaries. A mask (set with the mask command) determines how much of the expression 
is significant in the search, unless expression is a string constant The first three arguments 
to the search command arc sticky; thus if any of them are omitted then their previously 
specified value is used, f is the only debugger command which allows the specification of a 
string constant as expression. A string constant is delimited by the character " on cither 
side; to use " in the string itself, precede it with a \. An example of a string is: This is a 
string with V in it". The typcout limit of strings determines how much of the string is 
significant in the search, not the search mask. 

expression, m Set the search mask to expression. If expression is omitted then is used. -l,m forces a 
complete match, f,m (that's hex checks only the low order 4 bits, 0,m will make the 
search pattern match anything. 

9.3.6. Help Commands 

h Print a brief description of each of the debugger's commands. 

# Print a set of internal debugger statistics. This was implemented for the convenience of the 

designers and may change frequently in content and format It replaces the obsolete qq 
which, due to the debugger's unsophisticated command parsing will behave cxacdy as docs 
q. 

9.4. Bugs 

The debugger as it is currently implemented has some "features" one must be aware of.! 

Currently, the version of the debugger that runs on the Vax can only debug Vax programs, and the version 
that runs on the 68000 can only debug 68000 programs. This limitation causes little, difficultly since the 
debugger is ordinarily run on die same host as the program to be debugged. — \ 

Hie debugger assumes that any trace trap exceptions have been caused by its own single-stepping 
mechanism. Though it will recognize die first one, and print an error message, subsequent trap exceptions 
can cause intolerable behavior. 

The stackdump routines depend upon knowing the string names of the kernel routines to produce correct- 
stack traces which include those routines. Right now, this list is being kept up to date by hand. , 

Putting breakpoints in code which is shared by two or more processes can be hazardous to your mental 
health. .■■■•. 
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The draw program is a document illustrator that can be used to add figures to documents created with 
programs such as Scribe. This program is loosely based on the Xerox Alto Draw and SIL programs, and the 
Apple MacDraw program. Many of the same primitive objects are common to all four programs, but there 
are many features unique to V Draw. 

10.1. Conceptual Model 

Draw is an "object" oriented graphics editor as opposed to a "bitmap" oriented editor. This means that 
Draw allows you to freely manipulate the figures that you create after they have been placed on the screen at 
the expense of being able to do fine freehand sketching and other functions such as seed filling. 

The graphics model offered by Draw is very close to that provided by the underlying Virtual Graphics 
Terminal System (VGTS). All graphic objects manipulated by Draw are variations on three general types: 
splines, text, and groups. 

Splines are b-splines of order 2, 3, or 5. Order 2 splines have straight edges and are thus referred to as 
polygons. Order 3 splines use quadratic interpolation, and are thus referred to as curves. Circles use order 5 
splines which use quartic interpolation. Other shapes such as ovals, rectangles, and arrowheads arc special 
cases of the more general order 2 and 3 splines. Note that the term, spline, will be used to collectively denote 
all of these objects. 

Splines can cither be open or closed. Open splines have two ends. Closed splines do not have any 
endpoints. Any spline can have a border drawn with one of 15 pens or nibs. A closed spline may also be filled 
with any of 27 patterns. All splines must have cither a border, a fill pattern, or both. Fill patterns can cither 
be opaque or transparent. Any parts of objects lying behind an opaque object will not be visible. On the other 
hand, if the object is transparent, then it will act as a screen where the objects underneath will show through 
in the areas where the upper object is not black. 

Text objects allow you to place any type of written message on the page. Text can be in one of various 
fonts . It can also be cither left, center, or right justified. 

Groups do not have any graphic shape of their own, but arc used to keep various objects together. Any 
operation performed on a group is performed on all of its members. Groups can be nested; that is, one group 
may be a member of another group. This nested relationship is strictly hierarchical. No recursive nesting is 
allowed. 

10.2. Screen Layoult 

When die program is first invoked, it will create two new windows on the screen. The large empty one is 
the main drawing area (known as "drawing area" to the VGTS), and the smaller one is the commands window 
(known as "Draw menu" to the VGTS). The drawing area is zoomablc, and the grid spacing available at 
normal magnification is the same as that used by the program when the right mouse button is pressed. Since 
the program has no way of knowing what magnification you arc using, it aligns to the unzoomed grid values. 
The VGTS will place grid points at a constant separation, regardless of magnification. You may create 
additional views, move existing views, etc., to your satisfaction. Hie default drawing area is in the proportion 
of 8.5 by 11, and centered. A frame is put around the actual size of a drawing page to provide some reference 
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points if you zoom the view or change its centering. The frame is normally not visible, as it lies entirely 
outside the default view. It will not appear in any output While this rectangle defines the absolute bounds of 
the page, the default view defines the area which is "safe" to draw on since printers cannot, in general, print in 
the extreme margins. 

The menu window is shown in figure 10-1. 
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Figure 10*1: The Draw menu 

The Menu window is divided into several sections. Near the top, there is a set of square icons known as nouns. 
These define the various primitive objects which can be created with Draw. Along the left hand side arc the 
elongated verb icons. These define the types of transformations which can be performed on already existing 
objects. Below the nouns arc the nib and pattern sections, collectively known as the attribute section. These 
can be used to modify the appearance of all spline objects. Below these arc various Draw commands which 
arc used to perform various functions. Below the commands is a rectangle which displays the currently 
selected font. 'Iliis window displays the name of the font in its own typeface and is also used to set and 
display text justification. The Fontl and Font2 "commands" as well as the font rectangle also fall under the 
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heading of "Attributes" as these arc used to set text attributes like the nib and pattern sections arc used to set 
attributes of spline objects. At the very bottom of the menu is another rectangle where various Draw messages 
and prompts are displayed. 

The original window which you used to run the Draw program will serve as an area where text will be input. 
It is also used for printing unexpected error messages such as memory full errors. 

10.3. General style of interaction 

Almost all Draw interaction (except for text and filename input) is done with the mouse. To create an 
object, click on one of the noun icons in the menu and then click one or more times in the drawing area to set 
control points for that object. There are three types of objects: indefinite point objects, definite point objects, 
and text objects. Indefinite point objects, such as curves and polygons will accept input for an arbitrary 
number of points. To terminate one of these objects, click the Done command in the menu. Definite point 
objects, such as circles, rectangles, and arrowheads require a fixed number of control points. Each point 
displays a prompt in the message box which indicates what this point will be used for. For example, a circle 
first asks for a center point, and then for a point along the edge. Text objects ask for a single control point to 
position the text, and then prompt for the text string from the keyboard. 

Draw maintains a current object. This object is indicated by framing it with a rectangle. A newly created 
object becomes the current one. To change the current object, simply click on another one with any single 
mouse button. Draw will find the object that is closest to. the point that you click on and select that object. No 
object need always be current To un-sclcct all objects, click in a blank section of the drawing area window. 
More than one object may be selected at a time by using the TogglcSclcct or Range commands. This is 
provided primarily in order to create groups. 

To manipulate an object, first select it, thus making it the current object, and then click on one of the verb 
or attribute icons. Depending on the operation involved. Draw will request zero or more data points required 
to perform the given operation. These will be prompted for in the message rectangle. At any time, you can 
halt an operation with the 'Abort' command. If more than one object is selected, then the verb applies to all of 
the selected objects. 

10. 4„ Control Points and Sticky Points 

When you create a spline object (remember, this also includes polygons), you will be asked to specify its 
Control Points. Hicsc points arc the places which you wish the curve to pass near. Hie more control points 
you put in one place, the nearer the curve will come to that place. Also, placing multiple control points at a 
single point will make the curve much sharper at that point Kxccpt for the end points of open curves, and 
multiple control points, the curve will not, in general, pass through any of the control points. 

Sticky points (similar to Knots) arc points which actually lie on the curve. They arc calculated by the 
program to help you with the alignment of objects. There will be die same number of control points and 
sticky points on curves. Polygons arc a special case, in that since the control points of a polygon actually lie on 
it, the program considers them to be sticky points too. This means dial the sticky points on polygons lie at the 
cornci-s and in die middle of each edge. Circles also have a sticky point at their center. Sticky points for text 
objects arc on the left right, and center of the baseline (the line which most letters lie on top of, but which 
letters such as small 'p' descend below.) as well as die line just above die text Groups don't have sticky points 
for themselves but include any sticky points of objects within the group. This, in essence, means, that when 
looking for sticky points, all objects arc considered regardless of whether or not they arc part of a group, no 
matter how deeply the groups arc nested. 
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10.5. Mouse Buttons 

When the mouse is clicked inside the menu, it is unimportant which buttons you use. (The debug command 
is a hack and is the only exception.) 'Within a popup menu (a list of choice which 'pops up' after you do 
something), you can abort by either clicking outside the menu or by pressing all three mouse buttons down 
and releasing them. In general, you don't have to release (or press) the buttons all at once, but the mouse 
position is based upon where the cursor is when you release the last button. 

Clicking the mouse inside the drawing area can cause one of several different commands (and mouse 
locations) to be used by the program. The use of mouse buttons within the drawing area is as follows: 
Buttons Effect 

X - - Specifies a data point right where you are pointing. 

- X - Requests the program to find a sticky point. 

- - X Requests the program to use the nearest grid point. 
X X - The 'Again' command, (see below) 

X - X The 'ToggleSelect' command, (see groups below) 

- X X Equivalent to the 'Undo' command. 
XXX Equivalent to the 'Abort' command. 

Sticky points were explained above. When you request that the program select a sticky point, it will choose 
the nearest such point which is within a given radius (about 1 inch). 

Grid points arc spaced every 16 pixels (at normal magnification). If you wish to see these grid points, use 
the Toggle Grid command within the VGTS. For printed output, pixels are assumed to be distributed at 72 
per inch. 

The Again command allows the previous operation to be repeated. It is equivalent to issuing the Done 
command (if necessary) and then clicking in the icon for the previous operation. The mouse position where 
you issue the Again command is ignored as long as it is anywhere within the drawing area 

The easiest way to make fine adjustments to the position of an object is to first click on the Move verb icon, 
and then click on a source and destination data point. If you arc not satisfied with the move, click Again and 
repeat the operation without having to go all the way over to the menu. This command is also quite useful 
when drawing a scries of objects of similar type. You can specify that you wish to draw a closed curve, place 
the control points for the curve, and then confirm with Again. The program will complete the curve you have 
outlined, and wait for you to specify another closed curve, just as if you had confirmed with Done, and then 
selected Closed Curve again. 

The Abort command is used to cancel the current operation without creating or manipulating any objects. 
Abort will never throw you completely out of Draw. Use Quit for that' Some commands, such as Raise and 
I^owcr, are executed immediately and thus cannot be aborted. Use Undo to back out of these. 

The Undo and ToggleSelect functions are described more fully in the sections on Undo and Groups below. 

10.6. Verbs 

There arc eleven verbs in Draw. They arc indicated by the set of elongated icons along die left-hand side of 
the menu. Each is useful for manipulating one or more objects. All verbs require that an object be selected 
before they arc executed. Here they arc described as they appear from top to bottom. 

Move This verb will permit you to specify a pair of points which define a displacement vector. 

This vector tells the program how far and in which direction to move the object By using 
this command, you can move existing object about on the screen. 

Copy This verb is similar to Move, except diat it leaves behind an image of the object 

Erase This command allows you to delete (erase) the selected object This requires no extra data 
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points. If you make a mistake, you can always issue the Undo command. 

This verb is useful for changing the characteristics of an existing object It will permit you 
to move the control points on splines, change aspects of text objects, etc. (Not yet 
implemented) 

This verb will permit you to specify a fixed point about which the rotation is to take place, 
and two points which will define the angle of rotation. 

Text is rotated about its positioning point. Only the position of the text is changed; the 
orientation of individual letters is always horizontal from left to right 

This verb will permit you to specify a fixed point for the scaling, and two points which 
define the scaling factor. This command is useful for expanding and contracting objects. X 
and Y dimensions arc scaled equally. 

Scaling text will not change its size or font It will change the location of the string based 
upon its positioning point 

This verb is similar to the Scale command except that X and Y scaling is independent 
Thus an object may be made taller or shorter but not wider and vice versa. 

This verb binds a collection of objects into a group. If a single group is selected, it will 
un-bind that group back into a collection. Collections arc created with the TogglcSclcct 
mouse sequence to allow more than one object to be selected at one time. This, in a sense, 
creates a temporary group. The Group verb makes this permanent or makes a permanent 
group temporary. 

This verb will place the selected object on top of all of the other objects. Note that you can 
still point to objects you can't see; the program will find sticky points on completely 
obscured objects with no difficulty. 

This verb will place the selected object behind all of the other objects. This is useful when 
you use opaque ink to fill something, and it winds up obscuring an object you want to sec. 

This verb will toggle between opaque and transparent filled objects. Opaque objects 
completely obscure anything they overlap. Transparent objects act like a screen in that they 
allow what is under them to show through white areas. 



10.7. Nouns 

There arc eighteen icons in the noun section. These arc indicated by square icons near the top of the menu. 

Polygons and Curves 

There are three polygon icons and three curve icons. The three icons in each class 
correspond to open-unfilled, closed-unfilled, and closed-filled respectively. (It docs not 
make sense to have an open filled shape.) To create one of these types of objects, first select 
the icon, and then click on as many control points as desired, and then click on the Done 
command. You can also abort the object by clicking the Abort command cither from the 
menu, or by the (all three buttons down) mouse sequence. Closed unfilled polygons look 
just like open polygons except that no line is drawn from the last point back to the first 
Closed curves arc continuous and need not cross any control points. Open curves, however 
will begin and end at the first and last control point 

Arrowheads There are four types of arrowheads: wide-open, wide-closed, narrow-open, and narrow- 

closed. All arc entered in the same way. First the tip of the arrowhead is requested, and 
then its root Arrowheads arc separate objects from the main stem of the arrow and are 
generally placed allcr the stems have been drawn. 

Circles Circles come in two types - filled and unfilled. The two required data points arc the center 
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point and any point along the edge. Circles are the only shapes drawn as order 5 b-splines. 
Ovals and curves use order 3 b-splines. 

Ovals Ovals also come in filled and unfilled varieties. The data points are two opposite corners of 

the inscribing rectangle. The shape of an oval is exactly the same shape as would be 
produced by creating a curve, specifying the four corners of the inscribing rectangle as 
control points. 

rectangles These work exactly like ovals but with (Amazingly) straight edges! 

Text Creating a text object will first prompt for a single control point. This will specify the left, 

center, or. right side of the text at the baseline, (the bottom line which most characters 
touch. Letters such as p's and q's descend below the baseline.) Draw will then prompt for 
the text itself to be entered from the keyboard. 

PrcssEdit symbol (< = =«) . 

This is a special text object which is used to match a Draw illustration with a Scribe 
generated document when printing to a Press printer, (see the section below on including 
Draw-generated illustrations in documents.) 

10.8. Attributes 

Both text and spline objects have certain attributes. Text objects have font and justifications attributes. 
Spline objects have filling and border attributes. No attribute currently applies to both of these types nor to 
groups. Applying an attribute to a group, however, applies it to all of its members. 

Various functions in Draw can be used to change these attributes. These same functions set the default 
attributes for newly created objects. To change the attribute of an existing object, select it, and then click in 
one of the attribute functions in the menu. To set attributes for a new object, first un-sclcct any selected object 
by clicking in white space in the drawing area, set the desired attributes, and create the object Attributes can 
also be changed while an object is being created. The attributes that arc indicated when the object is 
completed arc the ones that stick. 

The following attributes arc available 
Fonts Fonts arc changed using the Fontl and Font2 commands. Even though these arc 

technically "commands" in that they appear in the commands section, they actually work 
more like attributes and arc thus described here. 

lk)th bring up a pop-up menu with a list of available fonts. Fontl provides some fairly 
standard fonts while Font2 provides some more exotic ones. Once a font is selected, it is 
loaded from disk if necessary, and then its name is displayed in the font rectangle in the 
menu in its own typeface. (Non- Ascii fonts such as Tcmplatc64 may look weird.) 

Text Justification There arc three different ways of positioning text: you can specify (with a data point 
entered via the mouse) cither the left-hand corner, the center, or the right-hand corner of 
the baseline of the text. This provides for left center, or right justification. Note that the 
baseline is the bottom line that most letters just touch. Small letters with descenders may 
actually go below the baseline. The current justification is indicated by the position of the 
name of the current font in the font rectangle. You will notice six small tick marks just 
inside the font rectangle which divide it into three parts. Clicking in cither the left, center, 
or right area will set the respective justification and move the font name accordingly. Note 
that the observed action if there is a text object selected in the drawing area is not 
intuitively obvious. Selecting left justification will cause an object to be shifted right if it 
was not already left justified. This is because the object's control point is kept stationary. 
(Think about it.) If you arc still confused about where text should appear, try positioning a 
few strings, using the exact positioning (leftmost) mouse button. 
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Nib Nibs select the "brush" that the borders of non-text objects arc drawn with. There arc 15 

different types of nibs arranged in a four-by-four square of four shapes (square, circle, 
dash, and bar), by four sizes. The sixteenth nib, corresponding to the smallest square is 
replaced by the letter "N" meaning (N)o border. The square shapes provide sharp corners 
while the circular shapes provide rounded corners. The largest of these also make nice dots 
if a polygon or curve is created with just one point. The dashes and bars create interesting 
calligraphic effects, especially for curves. The no border feature only applies to filled 
objects. Draw prevents you from accidentally making an object invisible by deleting both 
its boder and its fill pattern. 

Fill Pattern Next to the nibs are a set of 27 fill patterns arranged in a 4 x 7 rectangle. The 28th, at the 

top-left corner is marked with a letter "N" which stands for (N)o fill pattern. This is 
different to the one just to its right which looks blank. This is actually a white pattern 
which can be used to erase parts of objects that the white object overlaps. 

By default, all fill patterns are transparent. White areas of transparent objects allow objects 
below them to show through. This feature can be used to create interesting effects such as 
Venn diagrams. A fill pattern may be made opaque by clicking on the opaque verb which 
toggles the opacity of an object This means that any objects underneath it do not show 
through. The white pattern when transparent is equivalent to no fill pattern at all. 

•10.9. Commands 

Below the nib and pattern attribute section and above the font rectangle is the command section of the 
Draw menu. 

Done This command is used to terminate a curve or polygon which can have an arbitrary number 

of points. You will notice that the command is outlined in heavy black lines when it is 
appropriate. At other times, this command is equivalent to the Abort command. 

Undo This allows you to back-out of the previous operation. There are two levels of Undo in 

Draw. If you arc in the middle of an operation that requires multiple mouse clicks, then 
Undo will back out of the last mouse-click. Pressing Undo several times will cause more of 
the command to be undone until you back out completely from the command, 'llicre is 
also a global Undo which works by taking a snapshot of the currently visible objects on the 
screen just before each command is executed. Ten of these snapshots arc saved. Undo will 
bring back the previous snapshot The last ten operations can be backed out of in this way. 
Pressing Undo 10 times is effectively a redo because you return to the top of the circular 
Undo stack. This is handy in case that you pressed Undo too many times. Note that ALL 
operations can be undone - even Gear! Undo can also be executed by pressing the center 
and right mouse buttons simultaneously. 

Abort This command is used to back out of an operation which requires several mouse clicks 

completely. The state of Draw will be left as if the operation had never been started. Abort 
can also be executed by pressing all three mouse buttons simultaneously. 

Load This command is used to load files from disk. Anything loaded from disk is actually 

appended onto what may already be on the screen. To load only what is in the file, use the 
Clear command first Draw understands how to read several different file formats: its own 
V Draw files, Alto Draw files, Alto/V S1L files, and journal files. Obviously, V Draw files 
arc the preferred format as they describe all of the information that V Draw is capable of 
editing. Alto Draw and SIL file support is provided so that users who previously used one 
of these two drawing editors can port their files over. Unfortunately, the translation is not 
perfect For example, Alto Draw dashed lines and the "Arrows" font arc not supported. 
Journal files arc discussed below in the section about journalling. 

Save Although Draw can read files in the various formats discussed above, it will only write its 
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own V Draw files. Journal files are created by a completely different mechanism as 
discussed in "Jounalling" below. 

Print Draw supports two different types of printers: Press and Postscript . 

Press printers arc somewhat old, but rather fast workhorses which can print a page every 
second. The Press document format does not allow the full generality available in Draw. In 
particular, filled spline objects arc not supported and hence patterns, opaque, and even 
raise and lower operations do not affect the final output to Press printers. All of the fonts 
available in Draw, however, arc printable on Press printers. There are three Press printers 
at Stanford: Dover (Margaret Jacks Hall second floor), Rover (Margaret Jacks Hall fourth 
floor), and Plover (Durand building basement). The current page can be output to any of 
these printers directly from the Draw menu. 

Postscript printers arc more modern, but somewhat slower printers. A typical example is 
the Apple l^scrWritcr. Postscript printers are capable of displaying any graphic objects 
created with Draw. Only the printer's internal fonts are available, though. This includes 
the Helvetica and Times fonts. Also the Ascii font is mapped onto the Courier font, and the 
Greek typeface becomes Symbol. These translations are not perfect but they do work most 
of the time. Postscript printers tend to be owned by specific groups and arc not generally 
publicly available. For this reason. Draw checks to sec which printers arc available to the 
local UNIX V server and only displays those printers (if any). 

The Print menu, besides letting you send files directly to various printers, also allows you 
to save print files to disk for later printing or for inclusion inside other text documents. 
This latter operation is described in a section below. 

Range This command allows the selection of many objects simultaneously. The program will 

prompt for two control points which form opposite corners of a rectangle, it will then scan 
the entire list of objects and issue the ToggleScIcct command on any which intersect the 
given rectangle. Any unsclcctcd objects will be selected. Any previously selected objects 
will be unsclcctcd. To select all objects within a given rectangle, first click in a blank area to 
unsclcct everything, and then use the Range command to select the desired items. This 
command behaves exactly like issuing a ToggleScIcct on the given items individually. 

Gear This provides a method of completely wiping Draw's "slate" and starting from a fresh 

page. Ikcausc this operation is dangerous. Draw requires that you click on die command 
TWICK before it is actually executed. Even then, however, it can still be backed out of 
using the Undo command. 

Quit This is the best way to get out of the Draw program. Like the Clear command, above, it 

must be clicked on twice to actually be executed. For some strangely bizarre reason, Quit 
cannot be undone! The Undo button goes away, but so docs everything else, for that 
matter. 

Fontl and Font2 These two commands bring up menus which provide a selection of fonts. Fontl provides 
some more common fonts while Font2 provides more exotic ones. Selecting one of these 
will make it the current font. If a text object is already selected, it will change to die newly 
selected font. Otherwise, any newly created objects will use this font 

Help This command will provide a brief description of any other operation you like. To get help 

on a specific operation, just select that operation after you select help. To get help with the 
mouse buttons, push any one button in the drawing area. To exit help, select Help again. 

(Debug) This command is hidden. It can only be invoked by pressing all three mouse buttons in the 

message rectangle. This brings up a menu which provides several internal Draw debugging 
features which arc generally not of interest to the user. One function. "Keep journal," is 
documented below in the section on journalling. For the curious, you might also try the 
monkey which generates (pscudo) random events as if a monkey were at the keyboard and 
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mouse. (Don't worry. It's safe and protected from issuing dangerous commands like Save 
and Print!) 

10.10. groups 

Groups provide access to the structured graphics capabilities of the VGTS. A group is a collection of 
objects. Groups may contain other groups, but a lower level group, may not call a higher level group which 
called it Whenever possible. Draw tries to maintain a single conv of a group, even if it is called from many 
places. The only thing that differentiates two copies of a group when they are drawn on the screen is their 
absolute position. A group is created out of already existing objects at the top level. To create a group, use the 
ToggleSelect command (push the left and right mouse buttons simultaneously) or the Range command (from 
the commands section of the menu) to select more than one object Any un-selected object becomes selected, 
and likewise, any selected object becomes unsclcctcd regardless of the number of objects already selected 
Use ToggleSelect to affect individual objects and Range to change the selection status of a number of objects 
within a given rectangle. A set of selected objects work very much like a temporary group. Any modifications, 
such as rotation, scaling, or attribute changes, will be applied to all selected objects as if they were one object 
Selecting any other object or selecting nothing (clicking in white space) using the normal selection process 
undoes this "temporary group" but not any modifications that were made. To make a set of selected objects 
into a permanent group, use the group verb. This makes a set of selected objects into a group, and vice versa. 
In this way, groups can be created and destroyed. Groups arc highlighted with a heavy rectangle around all of 
the members. Once a group is created, any operations performed on the group arc performed on alt of its 
members. Clicking on any of its members selects the entire group, but clicking in white space that happens to 
lie inside the group rectangle docs not No operation may be performed on a member of a group without 
cither dismantling the group or affecting all other members. 

Groups are implcmntcd internally in a very efficient manner. For example, multiple copies of a group (or 
any object for that matter) arc only pointers to a single part Only when one of the copies is modified is a true 
copy made. This is all automatic, however, and the user need not worry about this. 

Use of groups may also speed up selection as a group who's bounding box docs not contain the given 
selection point is skipped and all objects within that group arc ignored. 

10.11. Inserting Draw pictures in text documents 

Draw has the capability of creating a file suitable for sending to a Press or Postscript printer, or for inclusion 
inside a Scribe document The method for doing this is slightly different for Press than for Postscript 

10.11.1. Press 

To insert a picture in a Scribe document first place a PrcssEdit symbol (a text item showing "<= =«") in 
the bottom center of your picture. Note that this symbol is already provided as one of the available prc-made 
objects in the Draw menu. This actually has some special significance to Draw as it will not allow you to 
change the font or the justification of this object. It will also be automatically skipped when creating Postscript 
output 

Choose the "Press file" option from the Print menu. You will be prompted for a file name. Because of the 
limitations of the Dover, filled splines and polygons cannot be printed. Itac objects will appear unfilled and 
a warning message will be displayed on the terminal. Some objects arc also just too complicated for the Dover 
to print In this case, cither garbage output will be produced, or the "press file too complicated" message will 
be printed on the header page with no other output 

Once the Press file has been created, you can now edit your Scribe file to automatically embed the picture 
in your document insert the line 

01 ibraryfile( picture) 



Using V 17 June 1986 



10-10 



draw: A Drawing Editor 



near the beginning of your scribe input (.mss) file, and lines like the ones shown below at the point where 
you want the picture to appear. 

...like that shown. in figure Qref (press-example). 

0Beg1n (Figure) 

0PressP1cture(file«"example. press", height»"3.4inches ) 

QCaptlon (An example figure) 
Stag (press-example) 
QEnd (Figure) 

This will produce output like that shown in figure 10-2. 




Figure 10-2: An example figure 

10.11.2. Postscript 

Postscript file inclusion is quite a bit different from Press printing. Fdr starters, the PressFxiit symbol is not 
used. Instead, Draw automatically figures out the extremes of the drawing and centers the picture accordingly. 
There arc two menu items in the Print .menu which generate Postscript files. The "(print later)" option create 
a file which is exactly like die one sent directly to the printers. The "(scribe)" version is suitable for inclusion 
in Scribe generated documents. 

Scribe requires a special variation on the normal Postscript device driver file in order to correctly print 
documents with Draw illustrations, 'lliis file, "vposts.dcv" must be cither in your local directory or in the 
Scribe daUibase directory. This file differs from the normal Postscript driver in diat it contains special header 
information which defines macros used by Draw pictures. To used this driver, place the line 
Qdevlce(Vpostscript) 

at the beginning of your scribe input (.mss) file, and lines like the ones shown below at the point where you 
want the picture to appear. 
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...like that shown in figure Qref (postscript-example). 

QBegin (Figure) 

QP1cture(Postscript»°example.psf", size«3.41nches) 
OCaption (An example figure) 
Stag (postscript-example) 
QEnd (Figure) 

This will produce output like that shown in figure 10-2. 

10.11.3. Both 

Often you will want to have a Scribe document which is printable on both types of printers. You would like 
to be able to have Draw generated illustrations in both Press and Postscript format, and have the Scribe file 
choose the correct illustration by just changing the ©Device command. To do this, add the @LibraryFile 
command at the top of your document as you would for a Press file, and add the following lines at the 
position whore you want the illustration to appear. 
QBegin (Figure) 
QCase ( Gene McDev ice, 

PRESS "§PressP1cture(File»example. press, height*3.4inches)". 
Postscript "9Picture(Postscript»example.psf , s1ze*3.4inches)") 
©Caption (An example figure) 
Stag (example-figure) 
QEnd (Figure) 

10.12. Journalling 

Whenever Draw starts up, it creates a file called "Draw.journal" in the local directory. In this file, Draw will 
keep a record of all user input events. If the program should crash in any way, the journal file will be left so 
that the entire Draw session can be re-constructed. Under normal circumstances, this file will be automatically 
deleted when you quit Draw using the Quit command. You can explicitly ask diat the journal file be kept 
around by choosing the "keep journal file" from the Debug menu which is found by pressing all three mouse 
buttons in the message area. 

Should you ever find yourself in the V debugger because Draw bombed, the best thing to do is to type 
"Quit,g" . This will cause Draw to clean up its windows and to ensure that the journal file is closed. 

A journal file can be played back by first renaming it so that it docs not get clobbered the next time that 
Draw runs and then using the Ivoad command to read it in like any other file. You will then sec your entire 
previous Draw session performed very quickly before your eyes. 

Note that journal files are extremely context sensitive. They depend on everything being exactly as it was 
when the journal was recorded. For example, if during the session, you loaded a regular file, edited it and 
saved it, the journal will probably fail because the file being loaded will be the new copy and not die old one. 
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1 1 .1 . Command format 

To start up a game of hack use the command 

hack -u playername -role -n -D -d directory 

All arguments are optional, and most are normally omitted. You can use the -u flag to specify your name on 
the command line. If this flag is not given, hack will use your V login name, or if you are not logged in, it will 
ask your name after starting. If your name is suffixed by a hyphen and a single letter, the letter specifies your 
character type. For example -u f red-t specifics that Fred wants to play as a Tourist You can also select a 
character without changing your name by giving the character type as a flag, e.g., -t to play as a Tourist The 
-n flag suppresses printing of the latest "hack news". (Usually there is no news anyway.) The -D flag lets 
you play in "wizard mode". It is (almost) impossible to die in this mode, and you get a free wand of wishing 
with 20 charges, but your score is not counted. This mode is mostly good for debugging the game. The -d 
flag specifics the directory hack is to use for storing temporary files, the score record, etc. If this flag is 
omitted, the default directory [sys] run/hack is used. 

To see the current scores without playing, use the command 

hack -s -roles playernames -d directory 

The -s flag is required. It may be followed by one or more role flags, or one or more player names to see 
scores for only those players or roles. If no player or role names arc given, hack prints only your own scores. 
The -d flag is optional and functions as described above. 

11.2. Description 

Hack is a display oriented game inspired by the popular Dungeons and Dragons fantasy game. Both 
display and command structure resemble rogue, but hack has many more types of monsters, magic items, and 
so forth. 

To get started you really only need to know two commands. The command ? will give you a list of the 
available commands and the command / will identify the things you sec on the screen. 

To win the game (as opposed to merely playing to beat other people high scores) you must locate the 
Amulet of Ycndor which is somewhere below the 20th level of the dungeon and get it out This is easier to do 
in hack than in rogue. 

When the game ends, cither by your death, when you quit or if you escape from the caves, hack will give 
you (a fragment ol) the list of top scorers. Hie scoring is based on many aspects of your behavior, but a rough 
estimate is obtained by taking the amount of gold you've found in the cave plus four times your (real) 
experience. Precious stones may be worth a lot of gold when brought to the exit There is a 10% penalty for 
getting yourself killed. 

The administration of the game is kept in the directory specified with the -d option, or, if no such option is 
given, a default directory specified at compile time. (Currently [sys]run/hack.) This same directory 
contains several auxiliary files such as lockfilcs and the list of top scorers, and a subdirectory save where 
games arc saved. 
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11.3. Options 

You may set options using the HACKOPTS environment variable, or the command within the game. 
The flag or command is followed by a comma-separated list of options. Available options arc echo, terschclp, 
name, onelinc, and passgo. A description of these is available through the ? command. All boolean options 
default to being false. To set a boolean option true, specify it in the option list To set your character's name, 
use the construct name->owr name. For example, to set terschclp, passgo, and your name to Yen Goi, the 
option string would be tersehel p , passgo » name«Yen Go1. You cannot change your name once you 
start playing. 

11.4. Authors 

Jay Fenlason (plus Kenny Woodland, Mike Thome and Jon Payne) wrote the original hack, very much like 
rogue (but full of bugs). Andries Brouwer continuously deformed their sources into the current version- in 
fact an entirely different game. Ported to the V-System, and additional hacking done, by Tim Mann. The 
V-System version is based on Andries Brouwcr's version 1.0.3. 

11.5. Files 

Files other than the hack program itself arc kept in the administration directory mentioned above, 

data Data flic for the / command. 

help, hh Data files for the ? help command, respectively the long and terse forms, 

news Hack news, printed whenever a game is. started, 

rumors Fortune cookie database, 

record The list of top scorers, 

save A subdirectory containing the saved games, 

boncs.dd Descriptions of the ghost and belongings of a deceased adventurer. 

11.6. Bugs 

Probably infinite. You can mail complaints to gamcs@Pcscadcro, but we suggest volunteering to fix it 
yourself if you want it fixed. 

This game is a huge time sink. 
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The s1l ed1 1 program can be used to edit simple illustrations. It is uses a compatible file format with the 
Alto SIL program, although some obscure features such as macros arc not implemented. The main limitation 
of this format is that only horizontal and vertical lines arc supported, with a limited range of fonts. On the 
other hand, it is simpler and faster than draw, and illustrations produced by s 11 ed1 1 can be easily inserted 
into other documents or printed out. A remote version of this program will run under Unix, although users 
will probably prefer the V-System version of the program if permitted by workstation memory limitations. 

1 2.1 . Basic Operation 

The s 1 1 ed 1 1 program is invoked with one argument: 
siledit filename. s11 

It first attempts to open the file name given as an argument If no such file exists, the program continues and 
allows one to be created. An SGVT is created, and the cursor should change to the "View" prompt indicating 
the creation of a default view. The default view will be slightly larger than the illustration, or a whole page if 
the illustration is empty. Press and hold any button an an outline the size of the default view will appear and 
track the cursor. Position the upper left corner of the desired default view with the cursor, and lift the button 
up when the view is in the right place. Next the $ 1 1 ed 1 1 program prints out the text fonts that will be used, 
and tries to load the appropriate fonts into the VGTS. Then the existing illustration is displayed, and the 
following prompt appears: 

Use mouse buttons: Nark, Select, Menu 

Thus two mouse buttons arc used for the basic commands, with other commands available through 
combinations of buttons or from the popup menu. 

The Mark, indicated by an "X" shaped cross, is used as one end of lines and the position of added text 
Once objects arc added to the illustration, they can be modified by first selecting them and then performing 
one of the modification commands. Selected objects will appear higlightcd in some way, although the exact 
form of the highlight is dependent on the VGTS implementation. In the SUN implementation, objects arc 
normally black on while, with selected lines appearing as half-tone gray and selected text appearing within a 
gray box. 

12.2. Commands 

l*hc commands available on the mouse arc as follows: 

Left Button Moves the mark to the point of die click. 'Hie "X" shaped cross moves to the new location. 

The mark is normally moved before drawing lines or placing text 

Middle Button Selects die single object at or near the click. Any other objects previously selected are no 
longer selected. The program will echo the kind of object selected, or issue a diagnostic if 
no objects arc found. 

Left + Middle Button 

Draws a line from the mark to the point of the click. The line is cither horizontal or 
vertical, depending on which difference in position is larger, 'lliis is a faster way of 
drawing lines than using the menu. The current line width is used for the line. The mark 
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is moved to the point of the click, to facilitate drawing a scries of connected line segments. 

Middle + Right Button 

Adds the object near the click to the selection. This is in contrast to the Middle Button, 
which causes exactly one object to be selected. Use this command to select several objects. 

Right Button Command menu, as described below. 

More advanced commands are available on the menu as follows: 
Quit Exits without saving the illustration. Usually you want to do the Write command first, so if 

there have been changes since the last Write command, confirmation is requested first 

Line Width Pops up another menu of default line widths. Select the desired hew width from 1 to 8 units. 
Clicking outside the menu results in no change to the width. 

Delete The selected objects are deleted. Currently there is no Undelete, so be careful! 

Unselect Another click is requested, and the object near that click will no longer be selected. 

Draw Line Another click is requested, and a horizontal or vertical line is drawn between the mark and the 
position of the click. 

Add Text A line of text is requested, and the text is added at the position of the mark in the current font 

Modify Text Selects another menu for modifying text 

Write Writes the illustration back to the file given on the command line. 

Stretch Line Position the cursor near one end of the selected line, and hold down a button. The end of the 
line will move following the cursor until the button is released. (Available only in the native 
V-System version.) 

Move Position the cursor anywhere in any view of the illustration and press any button. The selected 

objects will follow the cursor until the button is released. (Available only in the uative V- 
Systcm version.) 

Copy Position the cursor anywhere in any view of the illustration and press any button. A copy of the 

selected objects will follow the cursor until the button is released. (Available only in the native 
V-Systcm version). 

Box Move the cursor to one corner of the box, and press any button. While holding down the 

button, position the opposite corner of the box. The box will be drawn in die current line 
width. The box can be aborted by pressing all three buttons at the same time. (Available only 
in the native V-Systcm version.) 

Select Area Move the cursor to one comer of the area, and press any button. While holding down the 
button, position the opposite corner of the area. All objects within the area will be selected. 
(Available only in the native V-Systcm version.) 

Debug Enables several debugging print statements, for maintenance use only. (Available only in UNIX 

version.) 

Hie following commands arc used to modify text: 

Edit Text First select some text then issue this command. The text is stuffed into the VGTS line 

buffer, and edited by the user. 

Default Font Displays a menu of fonts to be chosen to become the new default font Text added with the 
Add Text command will use the new default font 

Change Font Changes the font of the selected text Displays a menu of fonts to be chosen as the new font 
for the selected text 



1 May 1986 V-Systcm 6.0 Reference Manual 



Commands 12-3 



12.3. Selecting Alternate Fonts 

Only two text font/size combinations arc available, but with all of the regular, bold and italic faces. Default 
fonts are Helvetica? and HclvcticalO, with Hclvetica7B, the bold face, Helvctica7I the italic face, etc. A third 
font, Templatc64, is used to draw circles and diagonal lines. A one-page chart of the Templatc64 character set 
is probably required to use any of these shapes. 

Other fonts can replace the two Helvetica fonts by creating a file with the name filename . fonts. This file 
should contain the names of the fonts to be used, one per line. Comments in this file arc indicated by a # 
character at the start of a line. The default fonts are acceptable for illustrations to be included in papers, but 
for slides larger fonts like 12 and 18 point should be used. Thus, for example, the font file: 

# font file for slides 

Helvetica^ 

Helvet1cal8 

could be used when making slides. The command: 

nm68 -d -g /usr/sun/11b/11bsfonts.a 
can be used to determine what fonts are available. This command lists the defined global symbols in the font 
library. 

12.4. Generating Printed Copy 

The $11 press program is used to produce the printed illustrations from SIL format. Currently this 
command only runs under Unix. Alternate fonts can be selected as in the slledlt program. The 
command line: 

stlpress filename. s1l 

will convert the named illustration into a Press format file and print it on the Dover. Most of the options 
available to the CZ program arc available in s 11 press. Use the man cz command for more details. In 
particular, the -p file, press option can be used to specify the name of a press file and inhibit printing. 
This is useful if the illustration is to be merged into a document produced with the Scribe or T^X document 
compilers. 

When using Scribe, include the command 
§Hbraryf1le( picture) 
near the beginning of your manuscript file. Then, for each illustration include the following commands: 

§Beg1n(F1gure) 

@PressP1cture( Height ■ "5.25 Inches", File ■ "filename. press" ) 

@Capt1on(A caption for this Illustration) 

8End(F1gure) 

Where the height is an estimate of the vertical size of the picture. Then place the character sequence <= =« 
with s 1 1 ed 1 1 near the bottom center of the illustration, and run s 1 1 press to create the Press file. The CZ 
program of Unix will insert the figures automatically. It usually several iterations to get the positioning and 
si/.c right, hut it is much faster than using a scissors and paste. 

! slledlt filename. s1l 

t sllpress -p filename. press filename. s1l 

t cz paper. press 

[Inserting filename. press on page 1] 
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The timeipc program performs timing tests of the V interprocess communication primitives (Send, 
Rece1ve[W1th$egm0nt;| f Reply[W1thSegment], MoveToandMoveFrom). 

To run the program, simply enter the command timeipc. For some tests, timeipc invokes a second 
program named timeipeserver to serve as a target for IPC messages; timeipeserver need never be invoked 
directly by users. 

13.1 . Types of Tests 

Timeipc allows you to conduct a number of tests. A test consists of a number of trials, A trial consists of a 
number of message transactions. 

Each test measures one of the following types of message transaction: 
Send-Rece1ve-Rep1y without segments 

Send-Rece1ve-ReplyW1thSegment with short segments 
Send-Rece1veW1thSegment-Reply with short segments 
5end-Rece1ve-MoveTo-Reply with long segments 

Send-Rece1ve-MoveFrom-Rep1y with long segments 

Short segments arc up to MAX.APPENDED.SEGMENT bytes long (1024 in the current version of the 
kernel). Long segments are longer than MAX_APPENDED_SEGMENT bytes. 

For each trial, the Sender process executes the following code: 

msgCounter ■ msgsPerTrlal; 

<record start t1me> 

do 

{ 
msg->tim1ngCode - typeOfTest; 
Send( msg, rece1verP1d ); 
1f( msg->tim1ngCode I- OK ) <abort tr1al> 

} 
wh1le( msgCounter— ); 
<record stop t1me> 

The Receiver process executes different code depending on the type of message transaction being tested. 
ForSend-Recelve-Reply tests, the Receiver executes: 

msgCounter ■ msgsParTrlal : 

do 

{ 

senderPId - Rec»1ve( msg ); 

1f( msg->t1mingCode I- typeOfTest ) <abort tr1al> 

msg->t1m1ngCode ■ OK; 

Rep1y( msg, senderPId ); 

} 
wh11e( msgCounter-- ); 
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For Send-Rece1ve-ReplyW1thSegment tests, the Receiver executes: 

msgCounter ■ msgsPerTrial ; 
do 

senderPId ■ Rece1ve( msg ); 

1f( msg->t1m1ngCode I- typeOfTest ) <abort tr1al> 

msg->t1m1ngCode ■ OK; 

ReplyW1thSegment( msg, senderPId, localSegPtr. msg->segPtr. msg->segSlze ); 

/• NOTE: lost reply segments are not detectedl */ 

wh1le( msgCounter— ); 

ForSend-RecelveVHthSegment-Reply tests, the Receiver executes: 

msgCounter • msgsPerTrial; 
do 

senderPId - Rece1veW1thSegment( msg, localSegPtr, &localSegS1*e ); 
1f( msg->t1«1ngCode I- typeOfTest || 

msg->segS1ze t- 1oca1SegS1ze ) <abort tr1a1> 
msg->t1mingCode ■ OK; 
Rep1y( msg, senderPId ); 

wh1le( msgCounter— ); 

ForSend-Recelve-MoveTo-Reply tests, the Receiver executes: 

msgCounter • msgsPerTrial; 
do 

senderPId - Rece1ve( msg ); 

1f( msg->t1m1ngCode !■ typeOfTest ) <abort tr1al> 

MoveTo( senderPId, msg->segPtr, localSegPtr, msg->segS1ze ); 

msg->t1m1ngCode - OK; 

Reply( msg, senderPId ); 

} 
wh11e( msgCounter— ); 

ForSend-Recelve-MoveFrora-Reply test, the Receiver executes: 

msgCounter ■ msgsPerTrial; 
do 

senderPId - Rece1ve( msg ); 

if( msg->timingCode !■ typeOfTest ) <abort tr1a1> 

MoveFrom( senderPId, localSegPtr, msg->segPtr. msg^segSIze ); 

msg->tim1ngCode ■ OK; 

Reply( msg. senderPId ); 

} 
wh1le( msgCounter— ); 
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13.2. Process Configurations 

Each type of test can be performed in any of the following three process configurations: 

(1) IPC between two processes on the same team. 

tlmelpc team 

>Root 

| (4) | ■■■■> indicates Sending of test messages 

| j > Indicates Sending of control messages 

| v (n) Indicates process priority 

Sender«*««>Rece1ver 
(1) (0/1/2) 

(2) IPC between two processes on different teams on the same host 

tlmelpc team : tlmelpcserver team 

>Root 



(4) 



I 



v 

Sender ■■■■■■■■■■ ■■■■■■■■■■■■■■■■•■■■■■■>Rece1ver 
(1) : (0/1/2) 

(3) IPC between two processes on different teams on different hosts. 

tlmelpc team : tlmelpcserver team 



>Root- 

(4) 



I 



v 



Sender ■■■■■■■»■■■■■■■■■ ■■■■■■■■■■■■■»««>Rece1ver 



(1) 

Looper 
(254). 



(0/1/2) 

Looper 
(254) 



Both timeipc and limeipeserver execute at RKALJTIMF1 team priority, giving their processes precedence 
over all other processes except the Kernel Process (or other teams executing at RKAI.JTIME1). For tests 
within a single host, the Sender and Receiver consume all processor cycles outside of the kernel, for the 
duration of a trial. For tests between hosts, each testing team runs an additional Looper process which loops 
forever, consuming and measuring all cycles not used by the Sender or Receiver. Thus, during a trial, the 
testing worksmtion(s) will appear to freeze - Uic cursor will not track mouse movement and keyboard input 
will be queued in the kernel. It is also possible that concurrently-running, time-dependent applications may 
suffer (e.g. TCP connections via Uic internet server may time out during a trial). 
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13.3. Input to timeipc 

Before each test, you must answer a series of prompts to specify the type of test and the process 
configuration for the test For each prompt, you may enter a null reply to request the default value specified 
in brackets, or enter tz to terminate the program, tc is ignored during prompting. 

receiver host name, 'local*, 'sameteanT, or 'quit'? [sameteam] 

Reply with the name of a workstation on which to execute the Receiver team, or enter one of the three, 
keywords. (The Sender team always executes on the workstation where the timeipc program was executed.) 
local requests that the test be performed between two teams on the local workstation, same team requests 
that only one team be used., qui t terminates the timeipc program. Any of the keywords may be abbreviated 
to a single letter. 

receiver at higher, same, or lower priority than sender? [lower] 
This prompt occurs if the test is to be performed within a single host Reply hi gher or h to run the Receiver 
at process priority 0, same or s for priority 1, or 1 ower or 1 for priority 1 • 

segment size 1n bytes, K bytes, or M bytes? [0] 

Specify the size of segment to be moved in the test message transaction. Don't leave any space between the 
number and the optional K or M suffix. A size of zero requests a simple Send-Rece1 ve-Reply test 

read or write? [read] if c 

This prompt occurs if a non-zero segment size was requested. read or r requests a 
Send-Rece1ve-ReplyW1thSegment test (if segment size <= MAX.APPENDED.SEGMENT) or a 
Send-Rece1ve-MoveTo-Reply test (if segment size > MAX_APPENDED_SEGMENT). write or w 1 
requests a Send-Rece1veW1thSegment-Reply test (if segment size <= 
MAX APPENDED SEGMENT) or a Send-Rece1ve-MoveFrom-Reply test (if segment size > r 
M AX J\PPEN DED.SEGMENT). 

number of messages per trial? [10000] i 

Enter the number of times the message transaction is to be repeated within a single trial. Note that 
MoveTo/MoveFrom operations arc not counted as separate transactions. 

number of trials? [10] . . <: 

Enter the number of trials to be performed. Enter zero to start the prompting all over again. 
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13.4. Output from f/rne/pc 

The results of the tests are written to stdout. All prompts and error messages arc written to stderr. 
Here is an example of test output: 

Send-Rece1ve-MoveTo-Rep1y test with 4096 byte segments 
between sender host 'nanalmo' and receiver host ' lubbock* 
600 messages per trial, S trials Wed Nov 6 16:60:16 1986 



trial 
number 


elapsed 
seconds 


elapsed 
usec/msg 


sender 
overhead 
usec/msg • 


receiver 
overhead 
usec/msg 


sender 
Idle CPU 
usec/msg 


receiver 
Idle CPU 
usec/msg 


seg rate 
bits/sec 


1 
2 

3 

4 
6 


13.030 
13.320 
13.490 
14.800 
13.020 


26060 
26640 
26980 
29600 
26040 


6 
5 
6 
5 
5 


6 
5 
5 
* 6 
6 


16022 
15618 
15889 
18387 
14925 


* 14859 
15263 
15764 
18255 
14686 


1257406 
1230030 
1214529 
1107027 
1258372 


avg. 


13.532 


27064 


6 


5 


16968 


15763 


1213473 



Not all columns arc printed for all tests, and the "avg." row is only printed when there is more than one trial 
per test. The meanings of the various statistics arc described here: 

elapsed seconds 

is the total elapsed time taken for the specified number of message transactions. It is determined by calling 
the kernel's Get Time function before and after the sequence of messages, and thus is only as accurate as 
GetTlme. Although it is printed to three decimal places, the current version of the kernel only keeps time to 
hundredths of a second, so the low-order digit should always be zero. 

elapsed usec/msg 

is the elapsed seconds divided by the number of message transactions, printed in microseconds. 

sender overhead usec/msg 
receiver overhead usec/msg 

arc the number of microseconds of "overhead" instructions expended for each message transaction, in the 
Sender process and the Receiver process. They arc computed by calling GetTlme before and after 50,000 
iterations of the transaction loop with the IPC primitives removed, and dividing by 50,000. 'lTicsc overhead 
values should be subtracted from the el apsed usec/msg to obtain the bare message transaction time. 

sender Idle CPU usec/msg 
receiver Idle CPU usec/msg 

arc only printed for tests between two hosts, and indicate for each host how many microseconds of the 
elapsed usec/msg arc spent waiting for the other host or the network. They arc measured by having a 
lower priority process on each machine that loops continuously, incrementing a counter. At the start of a trial, 
the counter is set to zero. At the end of a trial, the counter value is saved. Then, the loopcr is allowed to run 
alone for 1 second to determine how many times per second it can increment the counter. That rate is divided 
into the saved count to arrive at the printed value. 

seg rate b1ts/sec 

is only printed for tests with a non-zero segment size. It is the number of bits of segment data moved during 
the trial divided by the elapsed time of the trial. 
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13.5. Warnings and Precautions 

• Despite having exclusive access to process-level cycles on the testing workstation(s), the progam can 
yield different results for repetitions of the same test due to varying kernel overhead and network load 
For this reason, a test should consist of more than one trial, in order to observe the variance in the 
results. A number of steps can be taken to minimize these perturbations, depending on your need for 
accuracy: 

o Run the test at a time of low network load, even if you are only testing within one workstation - 
the kernel expends cycles receiving and handling arriving network packets. The mon program is 
very helpful for discovering the current network load (but not while a test is running!). 

Alternatively, isolate your workstation(s) from the network during the tests. For tests within one 
workstation, you can unplug the transceiver cable after you have started up the timeipc program. 
For tests between two workstations, you can connect them both to a DELNI which can be isolated 
from the network at the flick of a switch. (This is also a polite thing to do to avoid loading the 
network with your test messages.) Note that you will not be able to redirect your test output to a 
file if you have disconnected from the network. 

o Don't touch your keyboard or your mouse while a test is running - they cause interrupts that the 
kernel must handle. 

o Kill off any extraneous process that are running on your workstation(s), such as mon, telnet, 
internetserver, etc. I haven't figured out why their presence effects the results of the tests, but it 
does. 

o Be sure that you are logged-in in order to prevent others from remotely executing programs on 
your workstations). 

o Make sure no other REALJTIME1 teams are running on your workstation(s), such as other 
instances of timeipc or timeipeserver. 

o It is possible to run timeipc on top of a bare kernel, i.c. without any other teams present Only 
tests within a single team can be performed because the services of the team server arc not 
available to set up a separate receiver team. An example boot command to load timeipc onto a 
Sun2 workstation with 3Com Ethernet interface is: 

b V /usr/V/b1n/t1me1pc.m88k Vkernel/sun2+ec 
When running in this mode, answers to prompts must be entered using LINEFEED rather than 
RERJRN. You may safely ignore warnings about inability to set the team priority. 

(Currently, a simple Send-Rece1ve-Reply transaction on a Sun2 workstation is 6 
microseconds faster when performed on top of a bare kernel, compared to running on top of a 
freshly-booted standard first team and VGTS. Surprisingly, using the SIS instead of the VGTS 
makes the simple message exchange slower by 2 microseconds.) 

• Be aware that your workstation will appear to freeze up during a trial. You may enter tc to abort the 
test and return to the first prompt, but the interrupt will not take effect until the end of the current trial. 
If you don't know how long a particular trial will take, try it first with a small number of messages. 
However, test results for trials running less than a second or two should not be considered accurate, 

• For Send-Rece1ve-Rep1yVHthSegment tests, lost reply segments are not detected. Be wary of 
inter-host results from such a test 

• For Send-Rece1veW1thSegment-Rep1y tests, a trial will be aborted if the receiver docs not 
receive the sent segment. ITiis occurs if the receiver is not ready when the segment arrives, for example 
if the receiver is running at lower priority than a sender on the same host 

• Watch out for Vol's page mode - you may think you arc waiting for a trial to finish when in fact the 
program is blocked trying to write to your virtual terminal. 
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• Be aware that inter-host tests consume considerable Ethernet bandwidth (up to 3 megabits/second or 
more) and you arc in danger of becoming unpopular with other users of the network. 

• Timeipc does not currently measure the performance of Forward or any group IPC operations. 
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ved: A Text Editor 



Ved is the V system text editor. Its basic keyboard commands are a subset of Emacs. However, the mouse 
adds a whole new style of interaction with the editor. The multiple window capability of the VGTS is put to 
good use, as well. 

Ved manages one or more editing windows. Each window is thought of as a viewport onto a buffer of text, a 
continuously accurate display of some portion of that text A change to the buffer is followed immediately by 
a corresponding change to the display. In each buffer there is a cursor, which is guaranteed always to be in 
the portion of the text displayed. Each buffer normally has a filename associated with it, the file from which 
it was read or the file to which it was most recently written. 

14.1 Starting up 

Ved is invoked as follows: 

ved {-number} {filename} 
If a file name is given, Ved begins by reading in the file. It then requests an AVT, its first editing window. 
This is indicated by the mouse pointer, which changes to the word "Pad". Move the mouse to the desired 
upper left corner of the AVT and click any button. The AVT will appear, and in it the first screenful of text 
will be displayed. The AVT in which ved was invoked is reserved for displaying error messages and typing 
special text, such as filenames or search strings, which is not to be inserted into any buffer. Typing into this 
window while not specifically being prompted there for text will buffer those characters until input is 
requested. This is not, in general, the desired result In normal use it is convenient to shrink this window 
down to a few lines at the bottom. 

The number of lines in the AVT created for displaying a file can be specified with the -number option. The 
default size is 28 lines. 

At the top of the editing window, there is a banner. When the banner is inverted (darkened), dicn this 
window is selected for input cither by the mouse or the keyboard. The banner specifics the ved window 
number which is used by the window selection command (described in section 14. 13) and the Vgt number 
(sec section 2.4.2). The rightmost area is reserved for the file name associated with this window. If the file 
name has an asterisk (*) prefix, then ved thinks that this buffer has been modified since the last write or save 
of the specified file. 

As an added feature, there is a inverted line of text at the bottom of every ved window. This is the fixed 
menu area of the window. It can be used to enter some frequently used commands using the mouse instead 
of Uie keyboard (a full description of the fixed menu is in section 14.14.2). 

14.2. Some Notational Conventions 

In the subsequent command descriptions the following notational conventions will be used: 

• tk denotes hitting the CTRL key simultaneously with the k key. 

• Esc- A: denotes hitting the ISC' key followed by hitting the k key. 

• fk-j denotes hitting the C'IRI. key together with the k key, followed by hitting tficykcy. 

• Some keyboards have function keys that generate sequences beginning with Vsc-[. Where Uicsc arc 
supported by ved, they will be denoted by Ansi-*, meaning the sequence Esc-[-fc. 
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In general, there are (roughly) the following categories of key commands: 

• Regular key strokes: e.g. k. 

• "Control" characters: e.g. tk. 

• "Escape" characters: e.g. Esc-A:. 

• "Control-x" characters: e.g. tx-k. 

• "Control-x control" characters: e.g. tx-tfc. 

14.3. Special Commands 

tg Get out of special states. Whether you have just typed Escape or tX and didn't want to, or 

are busy typing a search string, or whatever, tg will get you back to the normal state. 

tx-tz, tc Quit the editor. If there are any modified buffers, you will be asked if you want to save 

them. If any .CKP files (files with .CKP suffixes are checkpoint files) have been created 
during this ved session, they will automatically be deleted. Here and in similar cases, if you 
are warned and then decide you don't want to do the command at alt, type tg to escape 
back to normal editing. Typing anything other than an n or y will cause the question to be 
asked again. 

tl (CTRL - L) Redraw the display. 

tu Prefix argument. Typing a number after this causes the number to be used as an input 

argument to the subsequent editing command. The prefix argument is only used by some 
commands. The others simply ignore it. tu is very similar (in intention at least) to the tu 
repcat'factor in Emacs. 

1 4.4. Cu rsor Motion 

tf, Ansi-c, right arrow 

Move forward (right) one character. 

tb, Ansi-d, left arrow 

Move backward (left) one character. 

Esc-f Move forward to the end of a word. 

Esc-b Move backward to the beginning of a word. 

tp, Ansi-a, up arrow 

Move up one line. A half page is scrolled if the cursor would go off the AVT. 

tn, Ansi-b, down arrow 

Move down one line. A half page is scrolled if the cursor would go off the AVT. 

ta Move to the beginning of the line. 

tc Move to the end of the line. 

Esc-comma, Ansi-h 

Move to top, left-hand corner of the viewport. 

Esc-pcriod Move to bottom, right-hand corner of the viewport 

Esc < Move to the beginning of the buffer. 

Esc > Mo vc to the end of the bu fTcr. 

Esc-g Go to line. Prompts for a line number, and moves the cursor to the head of that line in the 

file. The first line is numbered 1. If the number is too large, it will go to the end of text 
and notify you of the true line number there. 
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14.5,. Paging and Scrolling 

tv Page down 1 page. 

Esc-v Page up 1 page. 

Esc-down-arrow, Esc-Ansi-b 

Page down 1/2 page. 

Esc-up-arrow, Esc-Ansi-a 

Page up 1/2 page. 

tz Scroll one line up. I.e. move the viewport up one line relative to the text 

Esc-z Scroll one line down. I.e. move the viewport down one line relative to the test 

Esc-! Scroll current line to the top of the viewport 

14.6. Special Characters 

Typing any printing character, or TAB, inserts the character typed. Ved also supports an "auto-linefeed" 
mode. When auto-linefecd is enabled, typing in characters which would extend beyond the viewport's 
right-hand edge causes a linefeed character to be inserted before the last word on the current line. The effect 
is to split the current line into two lines, with the last word of the old line becoming the first word of the new 
line. This mode can be toggled on or off: 

tx-1 Toggle auto-linefecd option. 

Various special characters arc handled as follows: 

Return Insert a Linefeed, not a CR character- gets the desired effect 

Linefeed Insert a ncwlinc (Linefeed) and then indent the new line to the indentation of the previous 

line, using tabs where possible. If the previous line is empty, it will look up until it finds a 
nonempty line and use that as the standard of indentation. 

to Insert a Linefeed, leaving the cursor before it 

tq Quote the following character. Allows you to insert non-printing characters (such as the 

useful f 1, formfeed, which forces a page break on most printers) into the text 

t\ Quote the following character and insert it with the high bit set tq and t\ arc the only 

exceptions to the tg command: they will quote a following tg, but that simply means the 
insertion of a character, which can easily be deleted. 

14.7. The Kill Buffer 

Ved provides a special buffer, called the kill buffer, that is used to temporarily store text for various 
operations. Various editing commands specify this buffer as the source or destination of text they manipulate. 
The buffer should be thought of as a "clipboard" that is used for "cutting and pasting" operations on text 

14.8. Basic Editing Commands 

td Delete forward from the cursor- the character under the cursor, 

del, backspace, th Delete backward from the cursor, 
l^sc-d Delete word forward. 

Esc-h Delete word backward. 
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tk As in Emacs. Delete the contents of one (logical) line, or the carriage return on an empty 

line, into the killbuffcr. A sequence of tk commands uninterrupted by any other command 
causes the whole section thus deleted to go into the killbuffcr. tk after any other command 
restarts the killbuffer from scratch. 

ty Yank -insert contents of the killbuffcr at the cursor. The killbuffcr is unchanged. The 

cursor -ends up at the beginning of the insertion, and the Mark (sec below) ends up at the 
end. 

Esc-y Yank, but without disturbing the Mark. The cursor ends up at the end of the insertion. 

tt Transpose the two characters before the cursor. 

Esc-u Make the word the cursor is in, or just after, all capital letters. 

Esc-1 Make the word the cursor is in, or just after, all lower case. 

Esc-c Capitalize the word the cursor is in, or just after. 

Esc-tab Add indentation to this line equal to the indentation of the previous line. Intended use: if 

you type Return and wish you had typed Linefeed, this will make up the difference. 

Esc-blank, Esc-right-arrow, Esc-Ansi-c 

Indent the current line four spaces. 

Esc-backspace, Esc-th, Esc-lcft-arrow, Esc-Ansi-d 

Decrease the indentation of the current line four spaces. 

14.9. Mark and Region 

Vcd maintains an invisible point in the buffer called Mark. Until otherwise set it is at the beginning. It can 
be set by txtm or Control-® (Control-spacebar is the same as Control-® on some keyboards). "Region" 
refers to all the text between Mark and the cursor. The following commands use these concepts: 

tx-tm, t@ Set the Mark at the current cursor position. 

tx-tx Exchange Mark and cursor (changing the display if necessary to keep the cursor on the 

screen). 

tw, tx-tk Kill region. Region vanishes and becomes the killbuffcr- so this command can be undone 

with ty. 

tx-tr Write region. Prompts for a file name, and writes the region into that file. The buffer is 

unchanged. 

Esc-i Indent region. Indents all lines in die region by the number of spaces specified by the 

prefix argument If no prefix argument was specified, then all lines arc indented one space. 

14.10. C-Specific Editing Commands 

'Hie commands described in this section arc specific to the editing of C programs. 

Esc-{ Generate two new lines, the first containing a { indented two spaces from the previous 

cursor position, the second containing die cursor an additional two spaces indented. 

Esc-} Generate two new lines, the first containing a } indented two spaces less than the previous 

cursor position, the second containing the cursor indented an additional two spaces less. 
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14.11. Searching and Replacing 

ts Search for string. Prompts for a string, and finds the first instance of that string after the 

cursor. Prints "Not found" if there is no such instance. If you type Return without typing 
any search string, the previous search string is used. Here and elsewhere, a ncwline can be 
inserted into the search string using the Linefeed key. It is echoed as an inverse-video 
backslash. Non-printing characters can be searched for, and arc echoed as like "tA". If 
the search succeeds, the string found is selected, and several special commands (described 
in The Right Hand and the Left, below) are available. In particular, typing s will repeat the 
search. 

tr Reverse search. Just like ts but searches backward. 

Esc-s Repeat search. Forward search for the string most recently used in a ts or tr command. 

Works regardless of whether there is currently a selection or not 

Esc-r Repeat search backward. Like Esc-s but searches backward. 

Esc-q Query Replace. Prompts for a search string, then a replacement string. Then searches till 

it finds the search string, and selects that text. Type y (yes) to replace, n (no) to leave it 
alone and go on. Other options arc described below. These special commands are 
available whenever there is a selection, so Query Replace is easily re-enterable. 

tx-t Tag search. If a tags file is present in the current working directory, then this command 

can be used with it to find keywords in various files. 5 

14.12. File Access 

Vcd supports various options with respect to file writing operations and checkpointing operations. Files can 
be backed up and they can be written out using a "verify" option that ensures that what was written out is 
actually what is in a buffer. These options can be toggled on or off, as described below. Files can also be 
automatically chcckpointcd every n editing actions. Specification of the checkpoint frequency is done in the 
. Ved_pro initialization file. (Sec section 14.16.) 

When ved's backup option is on, it preserves the previous version of a file by renaming it to its former name 
followed by ".BAK". Thus myfilcc becomes myjile.c.HAK . Similarly, if the checkpointing option is on, files 
arc periodically written out to a file whose name consists of the actual filename followed by ".CKP". Thus 
myjtle.c becomes myJile.c.CKV . ITic verify option reads files back in after writing them and compares them 
against the buffer contents. Minis feature represents an end-to-end check that was implemented at a time when 
the V-systcm's file writing operations were not completely reliable. 

Upon normal exit from ved (by cither typing tx-tz, or tx-d to the last window) the .CKP files that were 
created during the current vcd session will be automatically deleted. If vcd exits abnormally, these files will 
contain a copy of your files that arc correct as of the last time checkpointing was performed* 

Vcd filenames can be up to 256 characters long, but filenames of this length arc not in general 
recommended. 

txtv Visit a file, whose name will be requested. The new file replaces the current one, so if the 

current buffer is modified you will be asked before proceeding. 

txts Write the buffer back to the file from which it was read. 

txtw Write the buffer to a file whose name will be requested. 



Ihosc unfamiliar with lags should read ihc unix manual entry for ctags. This command creates a file which specifics the location of 
every C-program function and lypc definition in a specified set of source files. It provides a means of locating such definitions without 
having to perform a string search on all source files each time. 
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txti Insert file at the cursor. You will be asked for the file name. Cursor and Mark are set just 

as in ty above. 

Esc-tm Write all modified buffers to the files from which they were read. Esc-Retum has the same 

effect 

Esc-~ Forget that the buffer has been modified. This will cause the file not to be written out on 

exit or when a command is given to write out all modified buffers. 

tx-b Toggle the .BAK safety feature. Creation of .BAK files makes file writing take about 4 

times as long as it otherwise would, so if you really want that speedup, this will turn off the 
making of .BAK files. Typing tx-b again will turn it back on. 

tx-v Toggle the verified write option. 

tx-c Change current context (working directory). The Ved control window always displays the 

absolute name of the current context in its banner, while file windows display the absolute 
path name of the file being edited. 

14.13. Windows and Buffers 

Ved is normally started with one editing window, but it can support several. Each editing window is 
associated with a separate editing buffer, which includes the text, cursor position, selection if any, associated 
filename, and whether this buffer has been modified. Multiple windows on the - same buffer are not 
supported. Since the correspondence is one to one, hereafter we refer to "window" meaning "window and its 
associated buffer". At any time one window is selected for editing, and has its banner inverted (darkened). 
Window selection can be changed by clicking a mouse button in an unsclcctcd window, or by tx-digit. 
Windows arc numbered, starting at 1, in the order of their creation. 

The search and replacement strings and the killbuffcr are universal across windows. Thus it is possible to 
kill some text in one window and yank it into another. It is likewise possible to search for a string in one 
window, then select another window and repeat-search on the same string. 

The window from which ved was invoked is special. It cannot receive input except during certain 
commands, at which time it is selected automatically. It is never receptive to mouse input 

tx-g Get file. Prompts for a file name, and reads it into a new window. If no file name is given, 

creates an empty window. Here and in all other cases, when a window is to be created the 
mouse cursor will change to "Pad" and let you indicate where the window is to go. If you 
abort the A VT creation by pressing all three buttons, the command is aborted. 

tx-G Get file and specify window.sizc. In addition to prompting for a file name, you also get 

prompted for the number of lines the window should have. 

tx-d Delete the current window. Will warn you if it is modified. The next lower numbered 

window becomes selected. If the last window is deleted, ved quits, because it cannot live 
without a selected window. 

tx-y Yank to window. The killbuffcr is copied into a new window. 

tx-a Pull Apart Kills the Region in the current window and transfers it to a new window. 

tx-m Merge windows. Asks the user to indicate a secondary window, and transfers its contents 

into the current window at the cursor position. The secondary window is then deleted. 
The secondary window is indicated by clicking the mouse in it 

tx-1 - tx-9 Select the corresponding window. 

tx-o Order buffers. Redisplays all die buffers, starting with the highest numbered one. This 

leaves tiic buffers "sucked" on top of each other on die screen. This is useful if buffers 
have been positioned in a "stair-casc ,r order, starting at the lower left and moving to the 



May 1986 V-Syslcm 6.0 Reference Manual 



Windows and Buffers 14*7 



upper right, so that the stacked configuration leaves the file name banner of each buffer 
displayed. 

14.14. The Mouse 

The mouse offers an alternative way of doing several common editing functions, such as placing the cursor 
and deleting or moving text The mouse has two functions: fixed menu selection and editing. 

14.14.1. Editing With the Mouse 

• 

Left button Click and release it at any character in the text: sets the cursor at that character. Click it at 

one character, move the mouse to another point in the window, and release: selects the 
text between the point of clicking and the point of release. While you arc moving the 
mouse with the left button held down, the region which would be selected if you released it 
at this moment is displayed in inverse video. When you release, your selection is defined 
and remains displayed in inverse video. Carriage returns are invisible, so the selection of a 
carriage return is shown by black space from the end of the text on that line to the end of 
the window. Note that a selection and a normal cursor arc mutually exclusive. The 
importance of this will become apparent below. If you have a selection and click the left 
button, with or without moving, the former selection is deselected and a new cursor 
position or selection is chosen. Caution: The difference between the cursor and a selection 
which is only one character long is that the cursor flashes, while the selection remains 
inverted. 

Middle button When you have a selection, clicking the middle button deletes it into the killbuffer. If you 
have no selection, nothing happens. The position of the mouse is irrelevant. 

Right button Brings back the contents of the killbuffer and makes it selected. If there is nothing in the 
killbuffer, nothing happens. If there was a selection already, its contents arc swapped with 
the contents of the killbuffer. If there was no selection, the contents of the killbuffer 
replace the cursor. 

14.14.2. Fixed Menu 

The fixed menu that appears at the bottom of every ved window provides the user with mouse oriented file 
perusal capabilities. Clicking the middle or right mouse buttons in the fixed menu area will execute the 
command that is nearest the mouse cursor. All the commands in the menu could be entered from the 
keyboard, therefore they arc not described here. Refer to the sections on searching, scrolling, and regions for 
descriptions. 

In the fixed menu area, the semantics of the each of the buttons differ. The middle button (in general) 
means forward whereas the right button means backward. For instance, clicking the middle button at the 
Full- Page command will cause the window to be scrolled forward one full page and the right button will cause 
a reverse scroll. The commands Half- Page. Scroll-IJnc. and Search behave in this same manner. The Tag 
command has exactly the same semantics for both buttons. Mark/Point is the only "different" command; in 
it, the middle button causes a jump to the Mark and the right button sets the mark at the point. Note that the 
left button has no effect on any menu selection, to maintain continuity during dynamic selection. Hie Search 
and Tag commands will cither use the selected string as the pattern or prompt the user for one in the case of 
no selection. 
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1 4.1 5. The Right Hand and the Left 

When there is a selection, the cursor is not in a single spot, so it would not make much sense to insert 
characters at the cursor. So various printing characters arc used as special selection-mode commands. The 
most basic of these commands arc all assigned to left-hand keys. Thus one possible mode of operation is for 
the user to have his right hand on the mouse, selecting things, and his left hand at the usual place on the 
keyboard, giving commands which are not available on the mouse buttons. Others of these commands are 
designed for use with the search and replacement facility. 

Non-printing characters other than those described below deselect, then perform their usual function as if 
the cursor had been at the beginning of the selection. 

space bar Deselect The cursor lands at the beginning of the selection. All printing characters not 

mentioned here also have this effect, but the space bar is recommended. 

tab Deselect, but the cursor lands following the end of the selection. 

d Delete. Exacdy identical to the middle mouse button. 

e Exchange. Exactly identical to the right mouse button. 

c Copy in place. A copy of the current selection is inserted right after it, and becomes the 

new selection. 

g Grab. The current selection is copied into the killbuffcr without deleting it. 

s Search for the next instance of the selected string. This becomes the search string, as used 

in future Repeat Search or search-and- replace commands. 

r Reverse version of s. 

tl (CTRL - L) Redisplay, with the selection near the top of the screen. Good for long 

selections which run off the bottom of the screen. 

y Yes replace. Replace the selection with the stored replacement string. 

n No don't replace. Search for the next instance of the stored search string. 

backspace Undo replacement. Search backward for the first instance of the replacement string and 

replace it with the search string. The resulting string is selected. 

Y Yes replace but don't move on. The selection is replaced and the result remains selected. 

u Undo in place. The current selection (which hopefully is the replacement string) is 

replaced with the search string. 

S Search for next instance of the replacement string. 

R Reverse version of S. 

q Start query replace. Takes the current selection as the search string, and" prompts for a 

replacement string. Replaces the current selection, and goes on to the next instance of it, 
just as "y" would do. 

Q Set replacement string. 'Hie current selection is copied into the replacement string. This 

makes it possible to alter a Query Replace in mid-flight 

t Tag search. Treats the selection as a tag and searches for its location using the tags file of 

the current working directory. 
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14.16. Ved Initialization 

Various ved features can be initialized to prespecified values using the . Ved_pro file, which should reside 
in the user's home directory. (The existence of this file is optional.) These include: 

• Redefinition of key bindings. 

• Specification of toggle settings for various options. 

• Specification of the checkpointing frequency. 

14.16.1. Key Bindings 

Ved uses a key table to determine what function should be invoked when a particular key or key sequence 
(such as tx-tc) is typed. The default settings in this key table have been described. The user can change the 
key table settings by specifying new bindings in the initialization file. The syntax to use for specifying new 
key bindings is demonstrated below in the list of default bindings shown. Thus, for example, one could set a 
new key binding that defined the tx-tm key sequence to denote WriteModificdFilcs instead of the Esc-tm 
key sequence, by placing the following line in one's . Ved_pro file: 
tx-tm WriteMod1f1edF1les 

The default key bindings are the following: 
\\r InsertReturn 
\\n NewllneAndlndent 
\\t InsertTab 

Esc-\\t IndentL1kePrev1ousL1ne 
tu ProvldePref ixArgument 
tx-tz ExitEditor 
tc ExitEditor 
tf ForwardCharacter 
Ans1-c ForwardCharacter 
narrow ForwardCharacter 
tb BackwardCharacter 
Ans1-d BackwardCharacter 
larrow BackwardCharacter 

ta Beg1nn1ng0fL1ne 
te EndOfUne 
tn NextLlne 
Ansi-b NextLlne 
darrow NextLlne 
tp Prev1ousL1ne 
Ans1-a PreviousLine 
uarrow PreviousLine 

tz ScrollOneLlneUp 
pfl ScrollOneLlneUp 
sm1-pfl ScrollOneLlneUp 
Esc-z ScrollOneLlneDown 
pf2 ScrollOneLlneDown 
smi-pf2 ScrollOneLlneDown 

Esc-f ForwardWord 
Esc-b BackwardWord 
Esc-u CaseWordUpper 
Esc-1 CaseWordLower 
Esc-c CaseWordCapitalize 
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tv NextPage 
Esc-v PreviousPage 
Esc-darrow NextHalfPage 
Esc-Ans1-b NextHalfPage 
Esc-pfl NextHalfPage 
Esc-sm1-pfl NextHalfPage 
Esc-uarrow PrevlousHalfPage 
Esc-Ans1-a PrevlousHalfPage 
Esc-pf2 PrevlousHalfPage 
Esc-sm1-pf2 PrevlousHalfPage 

tl RedrawDi splay 

Esc-, BeginningOfWIndow 

Ans1-h BeginningOfWIndow 

Esc-. EndOf Window 

Esc- 1 UneToTopOf Window 

Esc-< Beg1nn1ng0fF1le 

Esc-> EndOfFlle 

Esc-g GotoRequestedLine 

tx-t RequestTagSearch 

ts RequestStringSearch 

Esc-s RepeatStrlngSearch 

pf3 RepeatStrlngSearch 

smi-pf3 RepeatStrlngSearch 

tr RequestReverseStringSearch 

Esc-r RepeatReverseStrlngSearch 

pf4 RepeatReverseStrlngSearch 

smi-pf4 RepeatReverseStrlngSearch 

Esc-q QueryReplace 

th DeletePreviousCharacter 

del DeletePreviousCharacter 

td DeleteNextCharacter 

Esc-d DeleteNextWord 

Esc-h DeletePreviousWord 

tt TransposeCharacters 

to NewlineAndBackup 

tk KillToEndOfUne 

ty YankKillBufferAfterCursor 

Esc-y YankKillBufferBeforeCursor 

tx-tv VtsltFUe 

tx-ts SaveCurrentBuffer 

tx-tw WriteNamedFile 

Esc-tm Wr1teModif1edF1les 

Esc-} MarkUnmodif led 

tx-b ToggleBackup 
tx-v ToggleVer1fyWr1te 
tx-1 ToggleAutoLlneFeed 
tx-c ChangeContext 
tx-ti InsertFile 
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Esc-{ OpenBracal 
Esc-} CloseBracei 
Esc- IndentFour 
Esc-rarrow IndentFour 
Esc-Ansi-c IndentFour 
Esc-th OutdentFour 
Esc-larrow OutdentFour 
Esc-Ans1-d OutdentFour 

t SetMark 

tx-tm SetMark 

set-up SetMark 

tx-tx ExchangeDotAndMark 

Esc-1 IndentReglon 

tx-tr WriteRegloin 

tx-tk DeleteToKHIBuffer 
tw DeleteToKillBuffer 
tx-g V1sitF1leNewBuffer 
tx-G V1s1tFileNewBuffer 
tx-d DeleteWlndow 
tx-y YankToNewVMndow 
tx-a RegionToNewWindow 
tx-m MergeWlndows 
tx-1 GoToBuffer 
tx-2 GoToBuffer 
tx-3 GoToBuffer 
tx-4 GoToBuffer 
tx-5 GoToBuffer 
tx-6 GoToBuffer 
tx-7 GoToBuffer 
tx-3 GoToBuffer 
tx-9 GoToBuffer 
tx-o OrderBuffers 

Several editor flinctions exist that are not bound to any key by the default definitions. These are the 
following: 

OrdcrBuffcrBack wards 

Order the buffers in the opposite order of that used by OrderBuffers. Impending on 
whether a user prefers to stack their windows from lower left to upper right, or from lower 
right to upper left, one or the other of these ordering functions should be used. 

OpcnBrace Oprogram editing command. Generates three new lines, with the first and third line 

containing matching { and } braces indented two spaces from the original cursor position. 
The middle line is blank and indented four spaces from die original cursor position. 

CloscBrace Oprogram editing command. Hie same as CloseBracei, except that the second, blank line 

is not generated. Hie cursor is left after the } character. 

BackwardHackingTabs 

Same as DclctcPrcviousCharactcr except that tabs arc expanded first if they arc 
encountered. Thus, this command will convert a tab into 7 spaces instead of deleting the 
equivalent of 8 spaces worth of white space. 
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14.16.2. Specifying Options and Checkpoint Intervals 

Various options and the checkpointing frequency (in number of editing actions) can be specified in the 
initialization file. These include: 

(checkpoint number) 
(default rows number) 
(autolinefeed on/off) 
(backup on/off) 
(verifywrite on/off) 

The checkpoint specification expects an integer number between 1 and 2 32 -l. To turn off checkpointing 
specify some large number. The default is 500, which corresponds roughly to 'typing 10 lines of text The 
defauhrows specification sets the default AVT size. The other specifications expect cither an on or an off, 
indicating that the option should either be turned on or turned off. 

The case of the keywords used is unimportant- everything gets converted to lower case before parsing 
anyway. However, the parser is unforgiving of extraneous blanks in the specification. No blanks arc allowed 
between the parentheses and the keywords. (I know, this is easy to fix. It just hasn't been done yet) 

14.17. Crash Recovery 

In an ideal world, this program would never crash. But in fact it sometimes does- but it is so designed that 
it has to crash in two stages to lose your text Normally a crash only breaks the first stage, in which case you 
will generally drop into the debugger. At this point, the debugger command Suicide, g will destroy die 
process that got the exception. This will usually activate ved's crash recovery facility, signalled by the 
message: 

Editor crashl Shall I try to save this buffer? 

If you have any changes, and you value them, and the crash did not come during a save, it is probably a good 
idea to answer "y'\ A .BAK file will be made if the backup option has not been turned off, so the danger of 
total loss is small. If this succeeds you will be asked 

Try to continue? 
If you answer "y". the inner editor will be recreated with the buffers just as they were. For some display- 
related errors, a tL at this point will set everything right. However, you arc on shaky ground, and die best 
thing to do first is save any modified buffers in other windows. 

Remember that if the checkpointing feature was on when ved crashed, that dicrc may be good copies of 
your files chcckpointcd in your directory. Take a look at them before you panic, you may end up only losing 
a few lines of text 

Ved tries to detect the cases in which it runs out of memory. In some activities, such as reading in a file, it 
will simply refuse. In others, such as a kill or an insertion, you will get the message 
Out of memory I Please do one of the following: 
Pick a window to delete 
c - continue (after you free something) 
q - save and quit 
tC - quit without saving 

Ved cannot proceed without more memory, and cannot exit gracefully from this activity, so you have to help 
it out To pick a window, select it with one mouse click and signal it with a second click. It will be saved if 
modified, then deleted to reclaim its storage. If you have anything else going on on your Sun, you can delete 
a view or terminate a program or delete an exec to free some storage. After doing so, type c to continue. If 
this won't work, type q to try to save everything and quit gracefully. It will save the current buffer last trying 
to avoid the dangers of saving a half-modified text tc is a last resort a quick and dirty quit 
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14.18. Some Hints on Usage 

If you get into a weird state, try tl, it often restores sanity. If that fails, a save may work anyway -it uses 
only the textual data structures, and it is the display structures that usually foul up. 

Esc followed by a number key invokes one of the debugging routines. Avoid them, especially number 9, 
which is suicide. 
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xlisp: An Experimental Object Oriented Language 



This chapter is adapted from the document XLISP: An Experimental Object Oriented Language, Version 
1.4, January 1, 1985, by. David Bctz, 114 Davenport Ave., Manchester, NH 03103. 

15.1. Introduction 

XLISP is an experimental programming language combining some of the features of LISP with an object 
oriented extension capability. It was implemented to allow experimentation with object oriented 
programming on small computers. There are currently implementations running on the PDP-11 under UNIX 
V7, on the VAX-11 under VAX/VMS and Berkeley VAX/UNIX, and on the 8088/8086 under CP/M-86 or 
MS-DOS. A version is currently being developed for the 68000 under CP/M-68K and for the Apple 
Macintosh. It is completely written in the programming language 'C and is easily extended with user written 
built-in functions and classes. It is available in source form free of charge to non-commercial users. 
Prospective commercial users should contact the author for permission to use XLISP. 

Many traditional LISP functions arc built into XLISP. In addition, XLISP defines the objects 'Object' and 
'Cass' as primitives. 'Object' is the only class that has no superclass and hence is the root of the class 
hcirarchy tree. 'Class' is the class of which all classes are instances (it is the only object that is an instance of 
itself). 

This document is intended to be a brief description of XLISP. It assumes some knowledge of LISP and 
some understanding of the concepts of object oriented programming. 

Version 1.2 of XLISP differs from version 1.1 in several ways. It supports many more Lisp functions. Also, 
many version l.l functions have been renamed and/or changed slightly to follow traditional Lisp usage. One 
of the most frequently reported problems in version 1.1 resulted from many functions being named after their 
cquivilcnt functions in the C language. This turned out to be confusing for people who were trying to learn 
XLISP using traditional LISP texts as references. Version 1.2 renames these functions to be compatible with 
more traditional dialects of LISP. Version 1.3 introduces many new LISP functions and moves closer to the 
goal of being compatible with die Common Lisp standard. Version 1.4 introduces user error handling and 
breakpoint support as well as more Common Lisp compatible functions. 

A recommended text for learning LISP programming is the book "LISP" by Winston and Horn and 
published by Addison Wesley. The first edition of this book is based on MacLisp and the second edition is 
based on Common Lisp. Future versions of XLISP will continue to migrate towards compatibility with 
Common Lisp. 

15.2. A Note From the Author 

If you have any problems with XLISP, feel free to contact me for help or advice. Please remember that 
since XLISP is available in source form in a high level language, many users have been making versions 
available on a variety of machines. If you call to report a problem with a specific version, I may not be able to 
help you if that version runs on a machine to which I don't have access. Please have the version number of 
the version that you arc running readily accessible before calling me. 

If you find a bug in XLISP, first try to fix the bug yourself using the source code provided. If you are 
successful in fixing the bug, send the bug report along with the fix to me. If you don't have access to a C 
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compiler or arc unable to fix a bug, please send the bug report to me and I'll try to fix it 

Any suggestions for improvements will be welcomed. Feel free to extend the language in whatever way 
suits your needs. However, PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT 
CHECKING WITH ME FIRST!! I would like to be the clearing house for new features added to XLISP. If 
you want to add features for your own personal use, go ahead. But, if you want to distribute your enhanced 
version, contact me first Please remember that the goal of XLISP is to provide a language to learn and 
experiment with LISP and object oriented programming on small computers. 

15.3. XLISP Command Loop 

When XLISP is started, it first tries to load "iniUsp" from the default directory. It then loads any files 
named as parameters on the command line (after appending ".lsp" to their names). It then issues the 
following prompt: 

This indicates that XLISP is waiting for an expression to be typed. When an incomplete expression has 
been typed (one where the left and right parens don't match) XLISP changes its prompt to: 
n> 

where n is an integer indicating how many levels of left parens remain unclosed. 

When a complete expression has been entered, XLISP attempts to evaluate that expression. If the 
expression evaluates successfully, XLISP prints the result of the evaluation and then returns to the initial 
prompt waiting for another expression to be typed. 

Input can be aborted at any time by typing the CONTROL-G key (it may be necessary to follow 
CONTROL-G by REttJRN). 

15.4. Break Command Loop 

When XLISP encounters an error while evaluating an expression, it attempts to handle the error in the 
following way: 

If the symbol '*brcakcnablc*' is true, the message corresponding to the error is printed. If the error is 
correctable, the correction message is printed. If the symbol '*traccnablc*' is true, a trace back is printed. 
The number of entries printed depends on the value of the symbol '*tracclimit*\ If this symbol is set to 
something other than a number, the entire trace back stack is printed. XLISP then enters a rcad/cval/print 
loop to allow the user to examine the state of the interpreter in the context of the error. This loop differs from 
the normal top-lcval rcad/cval/print loop in that if the user types the symbol 'continue' XLISP will continue 
from a correctable error. If the user types the symbol 'quit' XLISP will abort the break loop and return to the 
top level or the next lower numbered break loop. When in a break loop, XLISP prefixes the break level to the 
normal prompt 

If die symbol '*brcakcnablc*' is nil, XLISP looks for a surrounding crrsct function. If one is found, XLISP 
examines the value of the print flag. If tins Hag is true, the error message is printed. In any case, XLISP 
causes the crrsct function call to return nil. 

If there is no surrounding crrsct function, XI .ISP prints the error message and returns to the top level. 

15.5. Data Types 

There arc several different data types available to XLISP programmers. 
• lists 
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• symbols 

• strings 

• integers 

• objects 

• file pointers 

• subrs/fsubrs (built-in functions) 

, > 

Another data type is the stream. A stream is a list node whose car points to the head of a list of integers and 
whose cdr points to the last list node of the list An empty stream is a list node whose car and cdr are nil. 
Each of the integers in the list represents a character in the stream. When a character is read from a stream, 
the first integer from the head of the list is removed and returned. When a character is written to a stream, 
the integer representing the character code of the character is appended to the end of the list When a 
function indicates that it takes an input source as a parameter, this parameter can either be an input file 
pointer or a stream. Similarly, when a function indicates that it takes an output sink as a parameter, this 
parameter can either be an output file pointer or a stream. 

15.6. The Evaluator 

The process of evaluation in XLISP: 

• Integers, strings, objects, file pointers, and subrs evaluate to themselves 

• Symbols evaluate to the value associated with their current binding 

• Lists are evaluated by evaluating the first clement of the list 

o If it evaluates to a subr, the remaining list elements are evaluated and the subr is called with these 
evaluated expressions as arguments. 

o If it evaluates to an fsubr, the fsubr is called using the remaining list elements as arguments (they 
arc evaluated by the subr itself if necessary) 

o If it evaluates to a list and the car of the list is 'lambda', the remaining list elements arc evaluated 
and the resulting expressions arc bound to the formal arguments of the lambda expression. 'ITie 
body of die function is executed within this new binding environment 

o If it evaluates to a list and the car of the list is 'macro', the remaining list elements arc bound to the 
formal arguments of the macro expression. The body of the function is executed within this new 
binding environment The result of this evaluation is considered the macro expansion. This result 
is then evaluated in place of the original expression. 

o If it evaluates to an object the second list clement is evaluated and used as a message selector. 
The message formed by combining the selector with the values of the remaining list elements is 
sent to the object 

15.7. Lexical Conventions 

The following conventions arc followed when entering XLISP programs: 

Comments in XLISP code begin with a semi-colon character and continue to the end of the line. 

Symbol names in XLISP can consist of any sequence of non-blank printable characters except the 
following: 

( ) ' ' . " 5 
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Upper and lower case characters are distinct. The symbols 'CAR' and 'car' arc not the same. The names of 
all built-in functions arc in lower case. The names of all built-in objects are lower case with an initial capital. 
Symbol names must not begin with a digit 

Integer literals consist of a sequence of digits optionally beginning with a '+' or *-\ The range of values an 
integer can represent is limited by the size of a C 'int' on the machine that XLISP is running on. 

Literal strings are sequences of characters surrounded by double quotes. Within quoted strings the 'V 
character is used to allow non-printable characters to be included. The codes recognized are: 

\\ means the character 'V 

\n means newline 

\t means tab 

\r means return 

\e means escape 

\nnn means the character whose octal code is nnn 

XLISP defines several useful read macros: 

'<expr> = = (quote <expr>) 

#'<cxpr> = = (function <expr>) 

4 <expr> = = (backquote <cxpr>) 

,<expr> = = (comma <expr>) 

,@<expr> == (comma-at<expr>) 

15.8. Objects 

Definitions: 

selector a symbol used to select an appropriate method 

message a selector and a list of actual arguments 

method the code that implements a message 

Since XLISP was created to provide a simple basis for experimenting with object oriented programming, 
one of the primitive data types included was object'. In XLISP, an object consists of a data structure 
containing a pointer to the object's class as well as a list containing the values of the object's instance variables. 

Officially, there is no way to sec inside an object (look at die values of its instance variables). ITic only way 
to communicate with an object is by sending it a message. When the XLISP cvaluator evaluates a list the 
value of whose first clement is an object, it interprets the value of the second clement of the list (which must 
be a symbol) as the message selector. The cvaluator determines the class of the receiving object and attempts 
to find a method corresponding to the message selector in the set of messages defined for that class. If the 
message is not found in the object's class and the class has a super-class, the search continues by looking at the 
messages defined for the super-class. This process continues from one super-class to the next until a method 
for the message is found. If no method is found, an error occurs. 

When a method is found, the cvaluator binds the receiving object to the symbol 'self, binds die class in 
which the method was found to the symbol 'msgclass', and evaluates the mcUiod using the remaining 
elements of the original list as arguments to die method. Hicsc arguments arc always evaluated prior to being 
bound to their corresponding formal arguments. The result of evaluating the method becomes the result of 
the expression. 

Classes: 
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Object THE TOP OF THE CLASS HEIRARCHY 

Messages: 

Show SHOW AN OBJECT'S INSTANCE VARIABLES 
returns the object 

class RETURN THE CLASS OF AN OBJECT 
returns the class of the object 

tsnew THE DEFAULT OBJECT INITIALIZATION ROUTINE 
returns the object 

sendsuper <sel> [<args>...] SEND SUPERCLASS A MESSAGE 
<sel> the message selector 
<args> the message arguments 
returns the result of sending the message 

Class THE CLASS OF ALL OBJECT CLASSES (Including Itself) 
Messages: 

new CREATE A NEW INSTANCE OF A CLASS 
returns the new class object 

1snew [<scls>] INITIALIZE A NEW CLASS 
<scls> the superclass 
returns the new class object 

answer <msg> <fargs> <code> ADD A MESSAGE TO A CLASS 
<msg> the message symbol 
<fargs> the formal argument 11st 

this list 1s of the form: 
(<farg>... 
[&opt1onal <oarg>...] 
[&rest <rarg>] 
[&aux <aux>. . .]) 
where 

<farg> a formal argument 
<oarg> an optional argument 
(default is nil) 
<rarg> bound to the rest of the 

arguments 
<aux> a auxiliary variable 
(set to nil) 
<code> a 11st of executable expressions 
returns the object 

ivars <vars> DEFINE THE LIST OF INSTANCE VARIABLES 
<vars> the 11st of instance variable symbols 
returns the object 

cvars <vars> DEFINE THE LIST OF CLASS VARIABLES 
<vars> the list of class variable symbols 
returns the object 

When a new instance of a class is created by sending the message 'new' to an existing class, the message 
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'isnew' followed by whatever parameters were passed to the 'new' message is sent to the newly created object 

When a new class is created by sending the 'new' message to the object 'Class', an optional parameter may 
be specified indicating the superclass of the new class. If this parameter is omitted, the new class will be a 
subclass of 'Object'. A class inherits all instance variables, class variables, and methods from its super-class. 

15.9. Symbols 

self the current object (within a message context) 

msgclass the class in which the current method was found 

*oblist* the object list 

*keylist* the key word list 

♦standard-input* the standard input file 

•standard-output* the standard output file 

*brcakcnable* flag controlling entering the break loop on errors 

*traccnable* flag controlling trace back printout on errors and breaks 

*tracclimit* maximum number of levels of trace back information printed on errors and breaks 

*evalhook* user substitute for the evaluator function 

*applyhook* (not yet implemented) 

♦unbound* indicator for unbound symbols 

15.10. Evaluation Functions 

(eval <expr>) EVALUATE AN XLISP EXPRESSION 
<expr> the expression to be evaluated 
returns the result of evaluating the expression 

(apply <fun> <args>) APPLY A FUNCTION TO A LIST OF ARGUMENTS 
<fun> the function to apply (or function symbol) 
<args> the argument 11st 
returns the result of applying the function 
to the argument 11st 

(funcall <fun> <arg>...) CALL A FUNCTION WITH ARGUMENTS 
<fun> the function to call (or function symbol) 
<arg> arguments to pass to the function 
returns the result of calling the function 
with the arguments 

(quote <expr>) RETURN AN EXPRESSION UNEVALUATED 

<expr> the expression to be quoted (quoted) 
returns <expr> unevaluated 
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(function <expp>) QUOTE A FUNCTION (THIS IS THE SAME AS QUOTE) 
<expr> the function to be quoted (quoted) 
returns <expr> unevaluated 

(backquote <expp>) FILL IN A TEMPLATE 
<expr> the template 
returns a copy of the template with comma and comma-at 

expressions expanded (see the Common L1sp 

reference manual) 



15.11. Symbol Functions 



(set <sym> <expr>) SET THE VALUE OF A SYMBOL 

<sym> the symbol being set 

<expr> the new value 

returns the new value 

(setq [<sym> <expr>]...) SET THE VALUE OF A SYMBOL 

<sym> the symbol being set (quoted) 

<expr> the new value 

returns the new value 



(setf [<place> <expr>]...) SET THE VALUE OF A FIELD 
<place> specifies the field to. set (quoted): 

<sym> the value of a symbol 

(car <expr>) the car of a list node 
(cdr <expr>) the cdr of a list node 
(get <sym> <prop>) the value of a property 
(symbol-value <sym>) the value of a symbol 
(symbol-pllst <sym>) the property 11st 

of a symbol 
<value> the new value 
returns the new value 



(defun <sym> <fargs> <expr>...) DEFINE A FUNCTION 
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(defmacro <sym> <fargs> <expr>...) DEFINE A MACRO 
<sym> symbol being defined (quoted) 
<fargs> 11st of formal arguments (quoted) 
' this list is of the form: 
(<farg>... 
[&opt1onal <oarg>...] 
[fcrest <rarg>] 
[&aux <aux>. . .]) 
where 

<farg> 1s a formal argument 
<oarg> 1s an optional argument (default nil) 
<rarg> bound to the rest of the arguments 
<aux> 1s an auxiliary variable (set to nil) 
<expr> expressions constituting the body of the 

function (quoted) ■ 

returns the function symbol 

(gensym [<tag>]) GENERATE A SYMBOL 
<tag> string or number 
returns the new symbol 

(Intern <pname>) MAKE AN INTERNED SYMBOL 

<pname> the symbol's print name string 
returns the new symbol 

(make-symbol <pname>) MAKE AN UNINTERNED SYMBOL 
<pname> the symbol's print name string 
returns the new symbol 

(symbol -name <sym>) GET THE PRINT NAME OF A SYMBOL 
<sym> the symbol 
returns the symbol's print name 

(symbol-value <sym>) GET THE VALUE OF A SYMBOL 
<sym> the symbol 
returns the symbol's value 

(symbol -pi 1st <sym>) GET THE PROPERTY LIST OF A SYMBOL 
<sym> the symbol 
returns the symbol's property list 



15.12. Property List Functions 

(get <sym> <prop>) GET THE VALUE OF A PROPERTY 
<sym> the symbol 
<prop> the property symbol 
returns the property value or nil 



30 April 1986 



V-Syslcm 6.0 Reference Manual 



Property list Functions 



15-9 



(remprop <prop> <sym>) REMOVE A PROPERTY 
<sym> the symbol 
<prop> the property symbol 
returns nil 



15.13. List Functions 

(car <expr>) 
<expp> 
returns 



RETURN THE CAR OF A LIST NODE 
the 11st node 
the car of the 11st node 



(cdr <expr>) 
<expr> 
returns 



RETURN THE CDR OF A LIST NODE 
the 11st node 
the cdr of the 11st node 



(caar <expr>) ■« 

(cadr <expr>) *•■ 

(cdar <expr>) ■« 

(eddr <expr>) ■« 



(car (car <expr>)) 

(car (cdr <expr>)) 

(cdr (car <expr>)) 

(cdr (cdr <expr>)) 



(cons <exprl> <expr2>) CONSTRUCT A NEW LIST NODE 
<exprl> the car of the new 11st node 
<expr2> the cdr of the new 11st node 
returns the new 11st node 

(11st <expr>...) CREATE A LIST OF VALUES 

<expr> expressions to be combined Into a 11st 
returns the new 11st 

(append <expr>...) APPEND LISTS 

<expr> lists whose elements are to be appended 
returns the new 11st 

(reverse <expr>) REVERSE A LIST 
<expr> the list to reverse 
returns a new 11st 1n the reverse order 

(last <Hst>) RETURN THE LAST LIST NODE OF A LIST 
<11st> the 11st 
returns the last 11st node 1n the 11st 
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(member <expr> <TI1st> [<key> <test>]) FIND AN EXPRESSION 

IN A LIST 
<expp> the expression to find 
<11st> the 11st to search 
<key> the keyword :test or :test-not 
<test> the test function (defaults to eql) 
returns the remainder of the 11st starting 
with the expression 

(assoc <expr> <a!1st> [<key> <test>]) FIND AN EXPRESSION 

IN AN A-LIST 
<expr> the expression to find 
<a!1st> the association 11st 
<key> the keyword :test or : test-not 
<test> the test function (defaults to eql) 
returns the allst entry or nil 

(remove <expr> <Hst> [<key> <test>]) REMOVE AN EXPRESSION 

FROM A LIST 

<expr> the expression to delete 

<l1st> the 11st 

<key> the keyword :test or :test-not 

<test> the test function (defaults to eql) 

returns the 11st with the matching expressions deleted 

(length <expr>) FIND THE LENGTH OF A LIST 
<expr> the 11st 
returns the length of the 11st 

(nth <n> <Hst>) RETURN THE NTH ELEMENT OF A LIST 

<n> the number of the element to return (zero origin) 
<Hst> the 11st 
returns the nth element 

or nil 1f the 11st Isn't that long 

(nthedr <n> <l1st>) RETURN THE NTH CDR OF A LIST 

<n> the number of the element to return (zero origin) 
<l1st> the 11st 
returns the nth cdr 

or nil 1f the 11st Isn't that long 

(mapc <fcn> <l1stl>. . .<l1stn>) APPLY FUNCTION 

TO SUCCESSIVE CARS 
<fcn> the function or function name 
<Hstl..n> a 11st for each argument of the function 
returns the first list of arguments 
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(mapcar <fcn> <!1stl>. . .<l1stn>) APPLY FUNCTION 

TO SUCCESSIVE CARS 
<fcn> the function or function name 
<listl..n> a list for each argument of the function 
returns the 11st of values returned 
by each function Invocation 

(mapl <fcn> <Hstl>. . .<Hstn>) APPLY FUNCTION TO SUCCESSIVE CDRS 
<fcn> the function or function name 
<Hstl..n> a list for each argument of the function 
returns the first 11st of arguments 

(mapUst <fcn> <Hstl>. . .<l1stn>) APPLY FUNCTION 

TO SUCCESSIVE CDRS 
<fcn> the function or function name 
<listl..n> a 11st for each argument of the function 
returns the 11st of values returned 

by each function Invocation 

(subst <to> <from> <expr> [<key> <test>]) SUBSTITUTE EXPRESSIONS 

<to> the new expression 

<from> the old expression 

<expr> the expression 1n which to do the substitutions 

<key> the keyword :test or :test-not 

<test> the test function (defaults to eql) 

returns the expression with substitutions 

(sublls <alist> <expr> [<key> <test>]) SUBSTITUTE 

USING AN A-LIST 

<a!1st> the association 11st 

<expr> the expression in which to substitute 

<key> the keyword :test or :test-not 

<test> the test function (defaults to eql) 

returns the expression with substitutions 



15.14. Destructive List Functions 

(rplaca <Hst> <expr>) REPLACE THE CAR OF A LIST NODE 
<list> the list node 

<expr> the new value for the car of the list node 
returns the 11st node after updating the car 

(rplacd <list> <expr>) REPLACE THE CDR OF A LIST NODE 
<Hst> the list node 

<expr> the new value for the cdr of the list node 
returns the 11st node after updating the cdr 

(nconc <l1st>...) DESTRUCTIVELY CONCATENATE LISTS 
<list> lists to concatenate 
returns the result of concatenating the lists 
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(delete <expr> <11st> [<key> <test>]) DELETE AN EXPRESSION 

FROM A LIST 

<expr> the expression to delete 

<Hst> the list 

<key> the keyword :test op :test-not 

<test> the test function (defaults to eql) 

returns the 11st with the matching expressions deleted 



15.15. Predicate Functions 

(atom <expr>) IS THIS AN ATOM? 

<expr> the expression to check 

returns t 1f the value 1s an atom, nil otherwise 

(symbolp <expr>) IS THIS A SYMBOL? 

<expr> the expression to check 

returns t 1f the expression 1s a symbol, nil otherwise 

(numberp <expr>) IS THIS A NUMBER? 

<expr> the expression to check 

returns t 1f the expression 1s a symbol, nil otherwise 

(null <expr>) IS THIS AN EMPTY LIST? 
<expr> the 11st to check 
returns t 1f the 11st 1s empty, nil otherwise 

(not <expr>) IS THIS FALSE? 

<expr> the expression to check 

return t 1f the expression 1s nil, nil otherwise 

(listp <expr>) IS THIS A LIST? 

<expr> the expression to check 
returns t 1f the value 1s a 11st node or nil, 
nil otherwise 

(consp <expr>) IS THIS A NON-EMPTY LIST? 
<expr> the expression to check 
returns t 1f the value 1s a 11st node, nil otherwise 

(boundp <sym>) IS THIS A BOUND SYMBOL? 
<sym> the symbol 

returns t If a value 1s bound to the symbol, 
nil otherwise 

(minusp <expr>) IS THIS NUMBER NEGATIVE? 
<expr> the number to test 
returns t 1f the number 1s negative, nil otherwise 
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(zerop <expr>) IS THIS NUMBER ZERO? 
<expr> the number to test 
returns t 1f the number 1s zero, nil otherwise 

(plusp <expr>) IS THIS NUMBER POSITIVE? 
•<expr> the number to test 
returns t if the number 1s positive, nil otherwise 

(evenp <expr>) IS THIS NUMBER EVEN? 
<expr> the number to test 
returns t 1f the number 1s even, nil otherwise 

(oddp <expr>) IS THIS NUMBER ODD? 
<expr> the number to test 
returns t 1f the number 1s odd, nil otherwise 

(eq <exprl> <expr2>) ARE THE EXPRESSIONS IDENTICAL? 
<exprl> the first expression 
<expr2> the second expression 
returns t 1f they are equal, nil otherwise 

(eql <exprl> <expr2>) ARE THE EXPRESSIONS IDENTICAL? 

(WORKS WITH NUMBERS AND STRINGS) 
<exprl> the first expression 
<expr2> the second expression 
returns t 1f they are equal, nil otherwise 

(equal <exprl> <expr2>) ARE THE EXPRESSIONS EQUAL? 
<exprl> the first expression 
<expr2> the second expression 
returns t 1f they are equal, nil otherwise 

15.16. Control Functions 

(cond <pa1r>...) EVALUATE CONDITIONALLY 
<pair> pair consisting of: 

(<pred> <expr>. . .) 
where 

<pred> 1s a predicate expression 
<expr> evaluated if the predicate 
1s not nil 
returns the value of the first expression whose predicate 
is not nil 



Using V 30 April 1986 



15 . 14 xlisp: An Experimental Object Oriented Language 

(and <expr>...) THE LOGICAL AND OF A LIST OF EXPRESSIONS 
<expr>... the expressions to be ANDed 
returns nil if any expression evaluates to nil, 

otherwise the value of the last expression 
(evaluation of expressions stops after the first 
expression that evaluates to nil) 

(op <expr>...) THE LOGICAL OR OF A LIST OF EXPRESSIONS 
<expp>... the expressions to be ORed 
returns nil 1f all expressions evaluate to nil, 

else the value of the first non-nil expression 
(evaluation of expressions stops after the first 
expression that does not evaluate to nil) 

(1f <texpr> <exprl> [<expr2>]) EXECUTE EXPRESSIONS CONDITIONALLY 
<texpr> the test expression 
<exprl> the expression to be evaluated 

1f texpr 1s non-nil 
<expr2> the expression to be evaluated if texpr 1s nil 
returns the value of the selected expression 

(let (<b1nd1ng>...) <expr>...) BIND SYMBOLS AND 

EVALUATE EXPRESSIONS 

(let* (<b1nd1ng>...) <expr>...) LET WITH SEQUENTIAL BINDING 
<b1nd1ng> the variable bindings each of which is either: 

1) a symbol (which 1s Initialized to nil) 

2) a 11st whose car 1s a symbol and whose cadr 

is an initialization expression 
<expr>... the expressions to be evaluated 
returns the value of the last expression 

(catch <sym> [<expr>]...) EVALUATE EXPRESSIONS AND CATCH THROWS 
<sym> the catch tag 
<expr>... expressions to evaluate 
returns the value of the last expression or 
the throw expression 

(throw <sym> [<expr>]) THROW TO A CATCH 
<sym> the catch tag 

<expr> the value for the catch to return (default nil) 
returns never returns 

15.17. Looping Functions 
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(do ([<b1nd1ng>]. . .) (<texpr> [<rexpr>], . .) [<expr>]...) 
(do* ([<b1nding>], . .) (<texpp> [<rexpr>], . .) [<expp>]...) 

<binding> the variable bindings each of which 1s either: 

1) a symbol (which 1s Initialized to nil) 

2) a 11st of the form: (<sym> <1n1t> [<step>]) 
where: 

<sym> is the symbol to bind 
<1n1t> Is the Initial value of the symbol 
<step> 1s a step expression 
<texpr> the termination test expression 
<rexpr>... result expressions (the default 1s nil) 
<expr>... the body of the loop (treated like a prog) 
returns the value of the last result expression 

(do! 1st (<sym> <expr> [<rexpr>]) [<expr>]...) LOOP THRU A LIST 
<sym> the symbol to bind to each 11st element 
<expr> the 11st expression 

<rexpr> the result expression (the default 1s nil) 
<expr>... the body of the loop (treated like a prog) 

(dotlmes (<sym> <expr> [<rexpr>]) [<expr>]...) LOOP FROM ZERO 

TO N-l 
<sym> the symbol to bind to each value from to n-l 
<expr> the number of times to loop 
<rexpr> the result expression (the default is nil) 
<expr>... the body of the loop (treated like a prog) 



15.18. The Program Feature 

(prog (<binding>...) [<expr>]...) THE PROGRAM FEATURE 
(prog* (<binding>...) [<expr>]...) PROG WITH SEQUENTIAL BINDING 
<b1nding> the variable bindings each of which 1s either: 

1) a symbol (which 1s Initialized to nil) 

2) a 11st whose car 1s a symbol and whose cadr 

1s an initialization expression 
<expr> expressions to evaluate or tags (symbols) 
returns nil or the argumen.t passed to the return function 

(go <sym>) GO TO A TAG WITHIN A PROG CONSTRUCT 
<sym> the tag (quoted) 
returns never returns 

(return [<expr>]) CAUSE A PROG CONSTRUCT TO RETURN A VALUE 
<expr> the value (defaults to nil) 
returns never returns 
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(progl <exprl> [<expr>]...) EXECUTE EXPRESSIONS SEQUENTIALLY 
<exprl> the first expression to evaluate 
<expp>... the remaining expressions to evaluate 
returns the value of the first expression 

(prog2 <exprl> <expr2> [<expr>], . . ) EXECUTE EXPRESSIONS 

SEQUENTIALLY 
<exprl> the first expression to evaluate 
<expr2> the second expression to evaluate 
<expr>... the remaining expressions to evaluate 
petupns the value of the second expression 

(ppogn [<expp>]...) EXECUTE EXPRESSIONS SEQUENTIALLY 
<expp>... the expressions to evaluate 
peturns the value of the last expression (op nil) 



15.19. Debugging and Error Handling 

(eppop <emsg> [<arg>]) SIGNAL A NON-CORRECTABLE ERROR 
<emsg> the oppop message string 
<apg> the argument expression 

(printed after the message) 
returns never returns 

(ceppop <cmsg> <emsg> [<apg>]) SIGNAL A CORRECTABLE ERROR 
<cmsg> the continue message string 
<emsg> the oppop message string 
<arg> the argument expression 

(printed after the message) 
returns nil when continued from the break loop 

(break [<bmsg> [<arg>]]) ENTER A BREAK LOOP 
<bmsg> the break message string 

(defaults to "**BREAK»«") 
<arg> the argument expression 

(printed after the message) 
petupns nil when continued from the break loop 

(erpset <expr> [<pflag>]) TRAP ERRORS 
<expp> the expression to execute 

<pflag> flag to control printing of the oppop message 
petupns the value of the last expression consed with nil 
or nil on oppop 

(baktrace [<n>]) PRINT N LEVELS OF TRACE BACK INFORMATION 
<n> the number of levels (defaults to all levels) 
returns nil 
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(evalhook <expr> <ehook> <ahook>) EVALUATE AN EXPRESSION 

WITH HOOKS 
<expr> the expression to evaluate 
<ehook> the value for *evalhook* 
<ahook> the value for *applyhook* 
returns the result of evaluating the expression 



15.20. Arithmetic Functions 

(+ <expr>...) ADD A LIST OF NUMBERS 
<expr>... the numbers 
returns the result of the addition 



(- <expr>...) SUBTRACT A LIST OF NUMBERS 
OR NEGATE A SINGLE NUMBER 
<expr>... ' the numbers 
returns the result of the subtraction 



(* <expr>...) MULTIPLY A LIST OF NUMBERS 
<expr>... the numbers 
returns the result of the multiplication 

(/ <expr>...) DIVIDE A LIST OF NUMBERS 
<expr>... the numbers 
returns the result of the division 



(1+ <expr>) ADD ONE TO A NUMBER 
<expr> the number 
returns the number plus one 

(1- <expr>) SUBTRACT ONE FROM A NUMBER 
<expr> the number 
returns the number minus one 

(rem <expr>...) REMAINDER OF A LIST OF NUMBERS 
<expr>. . . the numbers 
returns the result of the remainder operation 

(m1n <expr>...) THE SMALLEST OF A LIST OF NUMBERS 
<expr>... the expressions to be checked 
returns the smallest number 1n the 11st 

(max <expr>...) THE LARGEST OF A LIST OF NUMBERS 
<expr>... the expressions to be checked 
returns the largest number 1n the 11st 

(abs <expr>) THE ABSOLUTE VALUE OF A NUMBER 
<expr> the number 
returns the absolute value of the number 
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15.21. Bitwise Logical Functions 

(bit-and <expr>...) THE BITWISE AND OF A LIST OF NUMBERS 
<expr> the numbers 
returns the result of the and operation 

(b1t-1or <expr...) THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS 
<expr> the numbers 
returns the result of the inclusive or operation 

(bit-xor <expr...) THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS 
<expr> the numbers 
returns the result of the exclusive or operation 

(bit-not <expr>) THE BITWISE NOT OF A NUMBER 
<expr> the number 
returns the bitwise Inversion of number 

15.22. Relational Functions 

The relational functions can be used to compare integers or strings. The functions '=' and 7=' can also be 
used to compare other types. The result of these comparisons is computed the same way as for 'eq\ 

(< <el> <e2>) TEST FOR LESS THAN 

<el> the left operand of the comparison 

<e2> the right operand of the comparison 

returns the result of comparing <el> with <e2> 

(<- <el> <e2>) TEST FOR LESS THAN OR EQUAL TO 

<el> the left operand of the comparison 

<e2> the right operand of the comparison 

returns the result of comparing <el> with <e2> 

(- <el> <e2>) TEST FOR EQUAL TO 

<el> the left operand of the. comparison 

<e2> the right operand of the comparison 

returns the result of comparing <el> with <e2> 

(/• <el> <e2>) TEST FOR NOT EQUAL TO 

<el> the left operand of the comparison 

<e2> the right operand of the comparison 

returns the result of comparing <el> with <e2> 

(>- <el> <e2>) TEST FOR GREATER THAN OR EQUAL TO 

<el> the left operand of the comparison 

<e2> the right operand of the comparison 

returns the result of comparing <el> with <e2> 
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(> <el> <e2>) 
<el> 
<e2> 
returns 



TEST FOR GREATER THAN 
the left operand of the comparison 
the right operand of the comparison 
the result of comparing <el> with <e2> 



15.23. String Functions 

(strcat <expr>...) CONCATENATE STRINGS 
<expr>... the strings to concatenate 
returns the result of concatenating the strings 

(strlen <expr>) COMPUTE THE LENGTH OF A STRING 
<expr> the string 
returns the length of the string 

(substr <expr> <sexpr> [<lexpr>]) EXTRACT A SUBSTRING 
<expr> the string 
<sexpr> the starting position 
<lexpr> the length (default is rest of string) 
returns substring starting at <sexpr> for <lexpr> 

(asdi <expr>) NUMERIC VALUE OF CHARACTER 
<expr> the string 
returns the ascii code of the first character 

(chr <expr>) CHARACTER EQUIVALENT OF ASCII VALUE 
<expr> the numeric expression 
returns a one character string 

whose first character 1s <expr> 

(atol <expr>) CONVERT AN ASCII STRING TO AN INTEGER 
<expr> the string 
returns the integer value of the string expression 

(1toa <expr>) CONVERT AN INTEGER TO AN ASCII STRING 
<expr> the Integer 
returns the string representation of the integer value 

1 5.24. Input/Output Functions 

(read [<source> [<eof>]]) READ AN XLISP EXPRESSION 

<source> the Input source (default 1s standard input) 

<eof> the value to return on end of file (default nil) 

returns the expression read 
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(print <expr> [<s1nk>]) PRINT A LIST OF VALUES ON A NEW LINE 
<expr> the expressions to be printed 
<s1nk> the output sink (default 1s standard output) 
returns nil 

(pMnl <expr> [<s1nk>]) PRINT A LIST OF VALUES 

<expr> the expressions to be printed 

<sink> the output sink (default 1s standard output) 

returns nil 

(princ <expr> [<s1nk>]) PRINT A LIST OF VALUES WITHOUT QUOTING 

<expr> the expressions to be printed 

<sink> the output sink (default 1s standard output) 

returns nil 

(terpM [<s1nk>]) TERMINATE THE CURRENT PRINT LINE 

<s1nk> the output sink (default 1s standard output) 
returns nil 

(flatslze <expr>) LENGTH OF PRINTED REPRESENTATION USING PRINt 
<expr> the expression 
returns the length 

(flatc <expr>) LENGTH OF PRINTED REPRESENTATION USING PRINC 
<expr> the expression 
returns the length 

(explode <expr>) CHARACTERS IN PRINTED REPRESENTATION 

USING PRIM 
<expr> the expression 
returns the 11st of characters 

(explodec <expr>) CHARACTERS IN PRINTED REPRESENTATION 

USING PRINC 
<expr> the expression 
returns the list of characters 

(maknam <list>) BUILD AN UNINTERNED SYMBOL FROM 

A LIST OF CHARACTERS 
<!1st> 11st of characters in symbol name 
returns the symbol 

(Implode <list>) BUILD AN INTERNED SYMBOL FROM 

A LIST OF CHARACTERS 
<!1st> 11st of characters 1n symbol name 
returns the symbol 
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15.25. File I/O Functions 

(openi <fname>) OPEN AN INPUT FILE 
<fnaroe> * the file name string 
returns a file pointer 

(openo <fname>) OPEN AN OUTPUT FILE 
<fname> the file name string 
returns a file pointer 

(close <fp>) CLOSE A FILE 

<fp> the file pointer 
returns nil 

(read-char [<source>]) READ A CHARACTER FROM A FILE OR STREAM 
<source> the Input source (default 1s standard Input) 
returns the character (Integer) 

(peek-char [<flag> [<source>]]) PEEK AT THE NEXT CHARACTER 
<flag>. flag for skipping white space (default 1s nil) 
<source> the Input source (default 1s standard Input) . 
returns the character (Integer) 

(wrlte-char <ch> [<s1nk>]) WRITE A CHARACTER TO A FILE OR STREAM 
<ch> the character to put (Integer) 
<s1nk> the output sink (default 1s standard output) 
returns the character (Integer) 

(readllne [<source>]) READ A LINE FROM A FILE OR STREAM 

<source> the Input source (default 1s standard Input) 
returns the Input string 

15.26. System Functions 

(load <fname> [<vflag> [<pflag>]]) LOAD AN XLISP SOURCE FILE 
<fnante> the filename strin-g ( H .lsp" 1s appended) 
<vflag> the verbose flag (default 1s t) 
<pflag> the print flag (default 1s nil) 
returns the filename 

(gc) FORCE GARBAGE COLLECTION 
returns nil 

(expand <num>) EXPAND MEMORY BY ADDING SEGMENTS 
<num> the number of segments to add 
returns the number of segments added 
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(alloc <num>) CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT 
<num> the number of nodes to allocate 
returns the old number of nodes to allocate 

(mem) SHOW MEMORY ALLOCATION STATISTICS 
returns nil 

(type <expr>) RETURNS THE TYPE OF THE EXPRESSION 
<expr> the expression to return the type of 
returns nil 1f the value 1s nil, else one of the symbols: 
SYM for symbols 
OBJ for objects 
LIST for 11st nodes 
SUBR - for subroutine nodes 

with evaluated arguments 
FSUBR for subroutine nodes with 

unevaluated arguments 
STR for string nodes 
INT for Integer nodes 
FPTR for file pointer nodes 

(exit) EXIT XLISP 

returns never returns 
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— 16 — 
Standalone Commands 



This chapter discusses standalone programs, i.e., programs that do not run under the V kernel, that are 
useful with the V-Systejn. • 

16.1.Vload 

Vload is the V-Systcm bootstrap loader. The Vload program loads the V kernel and initial team into 
memory and starts up the kernel. 

There are several versions of Vload. Currently, all versions use the V I/O protocol and V IKC protocol to 
load programs over the Ethernet 6 On the Sun-1, the Sun 3 Mbit Ethernet board and Excclan 10 Mbit 
Ethernet boards arc supported as boot devices. On Sun-2s, the 3Com 10 Mbit Ethernet board and the built-in 
Ethernet interface of the Sun-2/50 arc supported. The standard Sun-3 cpu card (not the 3/50) and 
Micro Vaxcn with DEUNAs are also supported. 

Vload determines the files to load and other actions to take at run time, depending on what was typed on 
the command line and what information is stored in the configuration database for the workstation being 
booted (see section 19). For each of its parameters, Vload gives first priority to command-line information, if 
any, second priority to the defaults for this workstation recorded in the configuration database, if any, and 
third priority to a default value determined at compile time. / ! 

Team and kernel filenames arc interpreted in the V-Systcm "[sys]boot" context, unless they begin with a 
square bracket In the latter case, the name inside brackets is taken as a machine name. If "#" is given as the 
kernel file name, no kernel is loaded. Instead, the file specified as first team is loaded into the kernel's 
memory area and executed as a standalone program. 

Besides file names, two other parameters arc also understood: "world" and "options." The world may be 
cither V (production) or xV (experimental). 'ITic only option currently recognized is *b\ which causes a break 
to the prom monitor before the kernel is started. 

The following sections describe the defaults and special characteristics of the four versions of Vload in use 
at this writing. 

16.1.1. 3 MbitEtherhet 

■| i. 

This version of Vload is intended for booting Cadlinc, SMI Sun-1, and other Sun-1 workstation 
configurations with 3 Mbit Sun Ethernet boards. 'Ilicsc workstations ordinarily use a version of the Stanford 
i»rom monitor that incorporates l»UP bootstrap code. The first step in booting these workstations is to load 
Vload using the bootstrap pkoms. 'litis can be done by typing a keyboard command (b filename for SMI 
workstations, ti filename for others), or automatically on powcrup or reset (sec below). 

For these workstations, the kernel resides from 0x1000 to 0x20000, and teams arc loaded at 0x20000. 

The compilcd-in default values for Vload's parameters in this version are as follows: . , _ " ' \ 

world V ■ 



In the future, there will be a version of Vload that can boot a filcscrvcr machine directly from its local disk. 
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team tcaml-vgts 

kernel Vkemcl/sunl+en 

options null 

The only command line information visible to Vload is the name it was invoked under. Therefore, Vload is 
installed under several different names, and its action depends on its name. The names and actions are listed 
below. 

V When called under this name, Vload will load the team teaml-vgts and the default kernel 
for this workstation, using the default options. The team and kernel arc loaded from a V 
storage server (production versions) rather than an xV storage server (experimental 
versions), that is, the world parameter is set to V. 

V V The team is teaml-sts, and the world is V. 

x V The team is teamh vgts, and the world is x V. 

xVV The team is teaml-sts, and the world is xV. 

Vload The user is prompted for team, kernel, and options. The default value is used for any field 

where the user enters a blank line. The world is V. 

xVload Same as Vload, except that the world is set to xV. 

null If the name is null, Vload assumes it was autobooted. Default values are used for all 

parameters. 

others If a copy of Vload is installed under any other name, it will use its name as the team name 

to be loaded, set the options to null, and use defaults for the kernel and world. 

No special setup is required to get an SMI Sun-l processor to autoboot- it will do so automatically 30 
seconds after powcrup or a k2 command. The PUP boot PROM requests boot file number I by number, 
which causes a file called LBoot to be loaded from the first responding PUP EETP server. We have arranged 
for this file to be a copy of Vload, so the boot action is as described under the null name above. 

A non-SMI processor can be made to autoboot by installing the proper jumpers in its configuration register. 
(Sec the Sun User's Guide for a full description of the configuration register.) Bits 7-4 of the configuration 
register arc an index into a table of bootfile names stored in the PROM. An in-placc jumper or closed DIP 
switch corresponds to a bit; no jumper or an open switch corresponds to a 1. These bits should be set to the 
number corresponding to the name "Vload." Hie "W IT command typed to the prom monitor causes it to 
list the bootfile names and corresponding numbers that it knows about. Vload is usually number 5, 
corresponding to jumpers on bits 5 and 7. Vload's action will be as described under the null name above. 

16.1.2. Excelan Ethernet 

This version of Vload is intended for booting Cadlinc, SMI Sun-l, and other Sun-l workstation 
configurations with Excelan 10 Mbit Ethernet boards. Ordinarily, this version of Vload is used only with 
workstations using a special version of the PROM monitor that incorporates Tl TP bootstrap code. Hie first 
step in booting these workstations is to load Vload using the bootstrap proms. This can be done by typing a 
keyboard command, not described here. 

The compilcd-in default values for Vload's parameters in this version arc as follows: 
world V 

team tcaml-vgts 

kernel Vkcrncl/sunl+ex . 

options null 

The only command line information visible to Vload is the name it was invoked under. Therefore, Vload is 
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installed under several different names, and its action depends on its name. The names and actions are listed 
below. 

xlnV When called under this name, Vload will load the team teaml-vgts and the default kernel 

for this workstation, using the default options. The team and kernel are loaded from a V 
storage server (production versions) rather than an xV storage server (experimental 
versions), that is, the world parameter is set to V. 

The team is teaml-sts, and the world is V. 

The team is teaml-vgts, and the world is xV. 

The team is teaml-sts, and the world is xV. 



xlnVV 
xlnxV 
xlnxW 
xlnVload 



The user is prompted for team, kernel, and options. The default value is used for any field 
where the user enters a blank line. The world is K 



xlnx Vload Same as Vload, except that the world is set to x V. 

others If a copy of Vload is installed under any other name, it will use its name as the team name 

to be loaded, set the options to null, and use defaults for the kernel and world. 

There is currently no way to autoboot a workstation with TFTP boot PROMs. This limitation may be 
removed in the future. 

1 6.1 .3. 3Com Ethernet 

This version of Vload is intended for booting Sun-1.5s and Sun-2s with 3Com 10 Mbit Ethernet boards. 
These workstations boot using cither a local disk or tape, or the SMI network disk protocol. The network disk 
protocol does not allow specifying a file name, so the V-System ND boot server reads the boot file name from 
the workstation's configuration file; ordinarily, Vload will be specified. Once loaded, Vload can read the 
entire command line typed by the user. 

The compiled-in default values for Vload's parameters in this version are as follows: 

world V 



team 


teaml-vgts 


kernel 


Vkcrncl/sun2+ec 


options 


null 



Zero or more arguments may be passed on the command line to Vload If the first argument to Vload is 
one of the special values described below, it is stripped off and the special action listed is taken. After this 
check, the first three remaining arguments arc respectively used to override the defaults for team name, kernel 
name, and options. Values set by these arguments have priority over values that may have been set by the 
first argument 

V Sets the world to V, and the team to teaml-vgts. (This team name will be overridden by 

the next argument if present) 

VV The team is set to teaml-sts, and the world is V. 

xV The team is set to teaml- vgts, and the world is x V. 

xVV The team is set to teaml-sts, and the world is x V. 

null If no arguments arc present, the default values arc used for all parameters, 

vmunix The SMI boot PROMs have this name hardwired in for autobooting, so it is treated the 

same as a null first argument 

others If the first argument is not one of these values, the default world is used, and the arguments 

present specify team name, kernel name, and options, as described above. 
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For example, the command 

b V teaml-vgts [pescadero]/user/fred/mykerne1 .r 

will load the installed version of teaml-vgts as the first team, and a special version of the kernel from 
Pescadero. 

If the workstation being booted has a disk or some other device that the prom prefers over the Ethernet for 
booting, specify the boot device ec( ) immediately following the b in the boot command, and preceding the 
first argument (Some older prom revisions require nd( ) in place of ec( ). 

16.1.4. Sun-2/50 Ethernet 

The Sun-2/50 version of Vload is identical to the 3Com version described above, except that the default 
kernel is Vkerael/sun50. The boot device name is 1e( ). 

16.1.5. Sun-3 Ethernet 

The Sun-3 version of Vload is also similar to the 3Com version. The default kernel is Vkernel/sun3+ie, and 
the boot device is 1e( ). Currently a Sun prom monitor bug requires one to power cycle Sun-3 workstations 
when rebooting. Our Sun salesman has told us that new proms may be available. 

16.1.6. Micro Vaxen 

There are three switches on the back of the Micro Vax CPU. One is obviously the console baud rate selector. 
The other two have semi-random icons and affect booting. 

The flat switch, whose symbol is a triangle inscribed in a circle controls the halt button and auto-reboot 
With the switch at the dot-in-circle position the halt button on the face of the CPU halts the machine and 
forces it into the monitor, leaving you with a >» prompt Remember to press it once more to take the 
machine out of the halt state. When in the other, circlc-out-of-dot position, the halt button is disabled and any 
action which would cause a halt (such as a kernel halt instruction or a power failure) will cause a reset and 
auto-boot attempt 

The circular knob has three positions. The downward pointing arrow is the normal position. The outline of 
a face causes the proms to prompt for language and keyboard type. The T-in-circle is a test position. 

The commands for booting a Micro Vax arc: 

b Boot according to the config file specifications. 

b/1 Boot into the V world. 

b/2 Boot into the xV world. 

b/3 Boot into V, but prompt for the kernel and first team. 

b/4 Boot into xV, but prompt for the kernel and first team. 

If the disk drives arc enabled then b xqaO forces the bootstrap to load over the network. 

16.2. Netwatch 

netwatch is a standalone tool for examining packets as they arc spewn accross the ethcrnct It has 
knowledge of many different protocol formats, including V, IP, XNS, Chaos, and PUP. It maintains packet 
buffers sepcrate from those of the ethcrnct hardware for maintaining packet traces. 

We have found this to be the most powerful tool we have for debugging all nature of network protocol and 
distributed program communication bugs. This includes typical V distributed applications as well as protocol 
implementations (such as IP/TCP) on other hosts on our networks. There's nothing like silencing a roomfull 
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of random conjecture with a packet trace printout. The utility of looking at what's actually on the wire cannot 
be overemphasized. 

16.2.1. Booting 

netwatch runs standalone, so it must be booted fresh on a bare machine. A typical boot command to fire 
up the 3com version on a Sun-2 is: 
b V netwatch-ec2 # 

The sharp sign tells netwatch to load the first argument at the kernel start address and not to load a first team. 
Sec 16.1 for the details on booting other hardware configurations. Other versions of Vload supported are: 
netwatch-en (Sun-l/3Mb), netwatch-ec (Sun-l/3Com), netwatch-ec2 (Sun-2/3Com), 
netwatch-50 (Sun-2/50), and netwatch-1e3 (Sun-3/75). 

16.2.2. Operation 

The standard train of events is to set up the packet filters, then commence recording packets until a certain 
event has occurcd. When recording, packets which pass through the filter arc stored in a 127 buffer fifo 
queue. After recording the queue can be examined and/or written to a file. One may authenticate the 
netwatch process, which runs initially as unknown,, If your storage server allows the unknown user to 
write to /tmp this may not be needed. 

16.2.3. Commands 

The commands available at the top level are: 

h Modify host address filter (see 16.2.4.1). 

r Receive packets into bu ffer (flushes current buffer), 

t Same as r, but prints packets as they arc received (may drop packets), 

b Display buffer contents, 

s Same as b, but allows skipping of initial packets, 

w Write current buffer to a file. 

1 Login (authenticate), 

c Change default directory for file writing. 

! Print an cxclmation mark when a packet is received, 

m Always display the annoying option menu, 

q Quit. 

? Print a list of commands along with the current flag status 

16.2.4. Filtering by Packet Type 

netwatch understands several protocols, and can filter out packets based on die type field in the packet 
header. The packet types understood currently arc: V, ARP & RARP, Chaos (Symbolics), IP, PUP and XNS. 

16.2.4.1. tOmeg Address Filter 

The ten megabit packet filter is composed of two lists, the primary and secondary host lists. A packet is 
passed through die filter if its source and destination addresses can be found, one in each list Ten megabit 
host addresses arc specified using the last four hex digits of the cthcrnct address. At startup, the primary list is 



Using V 16 June 1986 



16-6 Standalone Commands 



empty and the secondary list is full (contains all addresses) with multicast turned ofF. Note: At the time of this 
release the nctwatch driver for the Intel 85286 chip (Sun-2/50 and Sun-3) randomizes the first short of die 
destination address, so filtering on multicast packets doesn't work on those versions. In basic operation, one 
fills the secondary list with all addresses, and enters the addresses of "interesting" hosts into the primary list 
Another typical use, when trying to debug communications between two hosts, is to have the two hosts in the 
primary list and all but one host (usually the the filescrvcr) in the secondary list 

16.2.4.2. 3meg Address Filter 

The 3 mcagabit host address filter maintains one list of hosts, and filters in one of two modes. In the first 
mode, AND mode, both the source and destination addresses must be in the list In the second mode, OR 
mode, only of the source or destination must be present Hosts addresses are entered in octal form. The entire 
eight bit address is used. 

16.3. Postmortem 

The Postmortem diagnostic tool is no longer supported. Much of its functionality has been put into the 
kernel funtions A11ens() and Processes (). On Suns these functions can be called manually from the 
monitor using the g <addr> command. The address of the function can be gleaned from the kernel's 
symbol table with cither debug -o 2000 <kerne!> or nm68. These functions arc not normally compiled 
into the Micro Vax kernel. 

16.4. Diskdiag 

The diskdiag program is a diagnostic program that allows one to manually access specific sectors on the 
disk. It is useful for verifying the correct interaction between the disk controller and disk drives, as well as for 
initializing a new disk. Diskdiag is configured to run on a system with a Xylogics 450 or Interphase 2181 disk 
controller and Fujitsu M2351 and M2284 disk drives. 

To run diskdiag, type the command 
b ec() diskdiag iP 
for SMI workstations, or 
n diskdiag 

for Cadlinc workstations. There arc commands available to format(f), read(r), seek(s), and 
wr 1 te( w). Hie user is prompted, as necessary, for more information on each of these commands. 

In addition, it is possible to label ( 1 ) the first sector of a drive with the configuration parameters needed 
by the disk driver in die kernel. Executing the format command automatically labels the disk after the format 
is complete. ITic verify (v) command reads me label off of disk and prints it on the console. 

The partltlon(p) command prompts the user for the start block and length of each partition on the 
disk and creates a disk partition table. Existence of a disk partition tabic is optional as it is not needed by any 
system software. The examlne(x) command allows one to examine the contents of the disk partition table. 

Reinitializing the diskdiag program is accomplished using die again (a) command. 

One should be aware of the fact that diskdiag's block size is the actual disk sector size, which may be 
different Uian the block size used by fseheck and the storage server. 



7 
Some SMI workstations with older PROM revisions require that ndQ be used in place of ocQ. 
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This chapter describes the execution environment provided for C programs written to run in the V-System. 
The program environment is designed to minimize the difficulty of porting C programs (and C programmers) 
from other C program environments, such as that provided by UNIX, and to provide access to the distributed 
programming facilities provided by the V-System. 

The program environment consists of three major components: 

• The base C language implemented by the compiler. 

• Routines that arc part of the C program library in most C implementations. 

• Functions that access V facilities. 

The basic C language is not described here. The reader is referred to The C Programming Language by 
B. W. Kcrnighan and D. M. Ritchie, Prentice-Hall 1978 for a tutorial on the language and standard C library 
routines. 

Standard C library routines arc only described here to the degree they differ in the V program environment 
from other implementations, particularly the UNIX C library. The reader is referred to the above-cited book 
or The Unix Programmer's Manual for details on these standard functions. 

The V-spccific functions are described in detail in the following chapters. 

While C as a programming language docs not define I/O facilities, memory management, etc., an ill- 
defined dc facto standard has arisen from the extensive use of C with the UNIX operating system. There has 
been a strong attempt to provide a superset of this environment for the V-Systcm. Attempts to port C 
programs have resulted in a slightly more portable program environment than originally used with UNIX. The 
functions included in the V program environment for C, excluding V and workstation-specific routines, 
constitute our proposal for a "standard portable C program environment". 

ITic differences between the V C program environment and die UNIX C program environment fall into four 
major categories 

• Functions that are UNIX system calls which may be provided as V library routines, e.g., stimc(). 

• Functions that arc slightly changed in their implementation, but provide (essentially) the same 
functionality, e.g., malloc(). 

• Functions that arc workstation-specific, because they arc not necessary in standard UNIX on, say, a Vax. 
For example, the long division routines arc in this category. 

• Functions that arc particular to the V-Systcm, like Crcatc() and Rcady(). 

17.1. Groups of Functions 

The description of functions is structured by subdividing them according to functional groups as follows, 
exec Functions related to the V executive. 

fields Functions that enable an AVT to be used as a menu, similar to a data entry terminal, 

io Input/output related routines, 

locking Routines providing locking for processes in a single team. 
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math Numeric and mathematical functions. 

mem Memory management and allocation routines. 

naming Name management functions. 

process Process service functions and V kernel traps. 

program , Program execution functions. 

user interface User interface routines 

others Miscellaneous other functions, such as string manipulation and time services. 

Subsequent chapters discuss each group of functions in greater detail 



17.2. Header Files 

The following header files define manifest constants, type definitions and structs used as part of the V C 
program environment. They are included as usual by a "# include <hcadername>" directive in C programs. 

Vauthcnticatch Message formats and definitions for the authentication server. 

Defines standard context directory entry formats and message types. 

Standard header file for V kernel types and request/reply codes. 



Vdircctory.h 

VcnvironJi 

Vctherneth 



Ethernet-specific header information. This is very low-level information; most users will 
want to use the Internet server instead. 

Vcxech Definitions for communication with the exec server. 

Vexccptions.h Exception types and exception request format 

Vfonth Standard internal bitmap and font format 

Vgroupids.h V well-known or static group identifiers. 

Vgtp.h Virtual graphics terminal protocol definitions and message formats. Must be known by the 

VGTS and stub routines that talk to it, but is not needed by ordinary VGTS applications. 

Vgts.h Virtual graphics terminal server interface. This should be included in any programs that 

do graphics. 

Vikch Manifests and constants relating to the V Intcrkcrncl Protocol. 

Vinfch Definitions and structs for InfoBase access. 

Vinfobuild.li Structs for building InfoBase. 

Vinfoparsch Definitions and structs for InfoBase scanner/parsers. 

Vio.h I/O Protocol header file. Types and mode constants for file manipulation functions 

described in chapter of Uiis manual. 

Vioprotocol.h I/O Protocol message formats. 

Vmachinc.h Machine-specific definitions. 

Vmigratc.h Migration-specific definitions. 

Vmousc.h Mouse device-specific header information. Most programs will use the VGTS to handle 

graphics input 

Vnaming.h V-Systcm naming manifests, types, and structures. 

Vncth Network server definitions. This is included in any programs that use the network. 
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Vpipch Definitions and structures for V pipes. 

Vprocess.h Processor state structure and other process-specific header information. 

VquerykerncLh QucryKerncl operation manifests and types. 

VscriaUi Manifests for the serial lines. 

Vscssion.h Manifests and message structs for the V/unix server. 

Vspinlock.h Definitions for spin locks, a cheap mechanism for locking within a team. 

Vstoragch Definitions and message formats for the V storage server. 

VtcamsJi Team header file. Structures used to communicate with the team server and to pass 
information to teams when they arc created. 

Vtermagenth Information shared by terminal agents and their clients. 

VtimeJi Structures used in time services, primarily for getting time from a session server. 
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A V-Systcm C program is constructed and executed similar to a C program on UNIX. Only the differences 
are discussed here. 

18.1 . Writing the C Program 

An application program on the V-Systcm starts to execute as a single process on a new team. By default, the 
process is allocated an initial stack area of about 4000 bytes, just above its uninitialized data segment. If this is 
not large enough (or is larger than necessary), the declaration 

1nt RootStackSlzer ■ newsize; 

can be used to set the initial stack size to newsize bytes. 

Note that large dynamically allocated areas of memory should be allocated using roal 1oc( ), cal loc( ), 
or a similar memory allocator, and not be allocated on the process stack. 

Warning: There is no run-tiime checking for overflowing the process stack allocation. The program behavior from stack 
overflow can be sufficiently bizarre as to cause good programmers to seek refuge in monasteries. If the stack overflow 
caused the process in question to get an exception, the standard exception handling routine will usually detect the overflow 
and print a message. I Iowcver. not all stack overflows cause an exception in the process that generated them, and sometimes 
the stack is back in bounds by the time the exception occurs. 

The file Venvl ron . h is a header File defining the types and constants that arise as part of the interface to 
the kernel. It is included by the line 
^include <Venv1ron.h> 

Programs that use the V input/output library usually need the file Vio.h, which corresponds to die UNIX 
header File stdlo . h. 8 Other V header Files, listed in the previous chapter, arc included similarly. 

18.2. Compiling and Linking 

When an application program is compiled and linked, references to kernel operations and other standard 
routines must be resolved by searching the library File 1 IbV. a. Its entry point must be the _start routine 
found in the library, and it must be relocated correctly for the target machine it is to run on. These defaults 
arc automatically selected with the -vV option of the cc68 or ccvax command. The compile command: 
cc68 -vV programf ile.c -o outputf i1e.m68k 

or for the Vax, 

ccvax -vV programf ile.c -o outputf He. vax 

produces an executable File for running with the kernel. The program environment provided by the 1 1bV. a 
library is described in the remaining chapters of this part of the manual. 



8 In fact, a V program may include $td1o . h in place of Vlo . h, since there is a V version of stdlo. h that simply includes Vlo . h. 
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I3>2 Program Constraclioo ami Execution 

18.3. Program Execution 

There are three models for executing V C programs, namely: 

1. running them in "bare kernel mode", that is, directly on top of the kernel 

2. running them from an executive 

3. running them as a subprogram of another program 

18.3.1. Bare Kernel Mode 

When a program runs in bare kernel mode, none of the standard servers are available, unless the program 
includes one or more of them itself (as described in Chapter 31). A program written to run in bare kernel 
mode begins execution at a procedure called mai n ( ). No arguments may be passed to the program. 

A program to be executed in bare kernel mode is loaded by a special loader program called VI oad. For 
example, on an SMI workstation: 

b Vload 
typed to the prom monitor causes it to load and execute the loader, which immediately prompts for the name 
of the file containing the program. The use of this loader is described more fully in Chapter 16. 

1 8.3.2. Execution With the Executive 

Use of the V executive is described in Chapter 3. Basically, one types the name of the file containing the 
program to the command interpreter followed by zero or more command arguments. The program is then 
loaded and executed. 

When the V executive is used, program execution again begins at a procedure called ma1n( ). This time, 
however, a count of the number of arguments to the program and an array of pointers to the program string 
arguments, as given on the command line, arc passed to the procedure. Moreover, the program is passed 
standard input, output, and error files, and a variety of other information through the TeamRoot message 
(described below in Section 18.4). 

The following example shows how a program can read its command line arguments. The variable argc 
contains the number of arguments including the command name. The arguments arc kept in argv[0] 
through argv[argc-l]; the command name is argv[0], argv[l] is the first argument, 
argv[argc-l] is the last argument, and argv[argc] is null. This matches the Unix convention. 

ma1n( argc, argv ) 
1nt argc; 
char *argv[]; 
/* Echo arguments */ 



{ 



1nt 1; 

for( 1 - 0; 1 < argc; ++1 ) 

pr1ntf( "%s ", argv[1] ); 
putchar("\n"); 



18.3.3. Subprograms 

A program may run another program as a subprogram by invoking the same library functions employed by 
the executive, 'llicsc functions arc described in Chapter 28. 
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18.4. Program Initialization 

Along with its compiler-generated code and data segments, a newly created program requires some 
additional run-time data about its environment before it can start execution. This data includes: 

• File instances for standard input, output, and error output, and associated flags. 

• Command-line arguments (argv and argc). 

• Initial values of environment variables. 

• Initial contents of the name cache. 

• Initial naming context (working directory). 

A program's creator passes this information to the new program in the team root message used to start its 
execution, extended by a team environment block of machine-independent format placed, in the new team 
space by the creator. This information is subsequently unpacked by an initialization routine (described 
below) automatically linked in with the new team. 

The format of the team root message and team environment block are given below, using a C-like notation 
with the following extensions: 

• The notation char a [ ] (an array of characters of unspecified size) means a null-terminated string. 

• The keyword repeat means that the following bracketed structure may be repeated zero or more 
times. 

• The notation al 1gn n means to insert null bytes to align the next field to an address evenly divisible 

by n. 

and the following common definitions: 

typedef Bit32 unsigned. long; /* unsigned 32-bit quantity */ 
typedef Bitl6 unsigned short; /* unsigned 16-bit quantity •/ 

18.4. 1 . The Team Root Message 

The team root message is sent to the new program just prior to its beginning execution (details below). It is 
formatted as follows: 

typedef struct 

{ 
#1fdef UTTLE.ENDIAN 

SystemCode replycode; 

B1U6 rootflags; 

Instanceld stdlnflle: 

Instanceld stdoutflle; 

Instanceld stderrflle; 

B1tl6 reservedl; 
rfelse LITTLE_ENOIAN 

BitlS rootflags; 

SystemCode replycode; 

Instanceld stdoutflle; 

Instanceld stdlnflle; 

Bltld reservedl; 

Instanceld stderrflle; 
#end1f LITTLE.ENDIAN 

Processld stdinserver; 

Processld stdoutserver; 

Processld stderrserver; 

Bit32 reserved?; 



/• Flags; see below */ 

/* Standard I/O instance Ids */ 



/* Standard I/O servers •/ 



/* Reserved for expansion of 
* Instanceld to 32 bits •/ 



TeamEnvlronmentBlock *teb; 



> 



RootMessage; 
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/* Root flags - bit assignments •/ 
#define RELEASE_INPUT 0x0010 
#define RELEASEJ)UTPUT 0x0020 
#define RELEASE_ERR J0xOO4O 
#def1ne STDOUT_APPENO 0x0001 
^define STOERR.APPENO 0x0080 



/* Release stdln on close •/ 

/* Release stdout on close */ 

/* Release stderr on close •/ 

/• Open stdout for append •/ 

/* Open stderr for append */ 



18.4.2. The Team Environment Block 

The team environment block is formatted as follows: 



typedef struct 

{ 

align 4; 

B1t32 blockslze; 
BH32 argc; 
repeat 

{ 
char arg[]; 

} 
args; 

align 4; 
B1t32 envc; 
repeat 

{ 

char name[]; 
char value[]; 

} 
env; 

align 4; 
B1t32 cachec; 
repeat 

{ 

align 4; 

ContextPalr from; 
ContextPalr to; 
BU16 flags; 
char name[]; 
char truename[]; 

} 
cache; 



/* Total size of block in bytes •/ 
/* Number of arguments */ 



/* Number of environment variables */ 



/• Number of cache entries */ 



> 



align 4; 

ContextPalr ctx; 
char ctxname[]; 
align 4; 



/* Initial naming context: 1denttf1er •/ 
/* Initial naming context: absolute name •/ 



TeamEnvlronmentBlock; 



Note that the team environment block, despite containing variable-length fields, can be unambiguously 
parsed IcIMo-righL 

Hie following library routine is available for creating team environment blocks: 



SystemCode SetUpEnv1ronment(p1d, args, env, cache, where) 

Processld p1d; 

char *args[]; 

EnvlronmentVaHable *env; 

NameCache 'cache; 

char 'where; 
Constructs a team environment block for the specified team, using the given argument vector, environment 
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variable chain, and name cache, and the caller's current working context. The team environment block is 
deposited in the new team space at address "where" (rounded up as necessary for alignment). 

18.4.3. The Per-Process Area 

In addition to sharing the team environment variables (extracted from the team root message and team 
environment block), each process on a team has a region of team memory reserved for its own use, called its 
stack space. A portion of the stack space, called the per-process area, is used to store a few process-global 
variables. (On the Sun and VaxStation, a process's stack grows downward from the highest address in its stack 
space, and the per-process area begins at its lowest address.) A team-global variable called PerProcess 
points to the per-process area* It is reset by the kernel to point to the correct area on every process switch. 

The standard per-process area is described by the PerProcessArea structure in the header file V1o.h. 
It contains the following values: 

stdlo An array of three File pointers describing the process's standard input, output, and error 

files. <Vio.h> defines the macros stdln, stdout, and stderr to be PerProcess-> 
std1o[0], PerProcess->std1o[l], and PerProces3->stdio[2] respectively. 
Note that only pointers, not the File structures themselves, are kept in the per-process 
areas. 

ctx A ContcxtPair structure giving the context identifier of the process's current naming 

context (working directory). 

s t ackS 1 ze The size of the process's stack space, in bytes. 

ctxname A character string giving the absolute name of the process's current naming context These 

strings arc allocated on the heap (i.e., by ma11oc()) and are freed by the 
ChartgeDI rectory ( ) library routine. 

env A pointer to the list head for this process's environment variable list 

namecach a A pointer to the list head for this process's name cache. 

A newly created process on the same team as its parent (if created with the standard Create() library 
routine) inherits a copy of its parent's per-process area, with the exception of the stackSize field, which is 
specified as a parameter to Create( ), and the ctxname pointer, which is modified to point to a fresh copy 
of the string to avoid the need for reference counting such strings. Thus, each child process inherits its 
creator's standard I/O, current naming context, name cache, and environment variables. 

18.4.4. Initialization Procedure 

A new program is created in the awaiting reply state, waiting for a (reply) message from its creator. In 
effect, the kernel simulates a Send from the initial process of the program to its creator, in response to which 
the creator must Reply before the program can begin execution. Prior to replying, the creator has access to 
the new team's entire address space and uses CopyTo( ) to deposit the team environment block of the new 
program. 

Nolo: ITic creator is responsible for passing (he In- and 32-bit fields in the team environment block in the correct bylc order 
Tor the new team's host machine. This is in accord with the general convention that senders or messages use their native 
byte order, with receivers being responsible Tor byte-swapping if necessary. In this case, the new team is logically the sender 
in its initial transaction. 

Finally, the creator invokes Reply ( ) to set the new program running; the reply message constitutes the team 
root message. (Sec Chapter 27 for details of the interprocess communication primitives used.) 

Meanwhile, the new program is blocked in the middle of its. initialization code. This code is structured as a 
small assembly-language routine containing the team's initial entry point (_start), plus a machine- 
independent routine TeamRoot(), called from _start. _start initializes the stack, receives the team 
root message, zeros the initial data segment (bss) and then calls TeamRoot() to do the rest of the 
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initialization. TeamRoot( ) "unpacks" the team root message and team environment block, placing pieces of 
data in global variables or on the stack or heap as required by the host machine and programming language. 
The team environment block is discarded after having been unpacked; generally, the memory it occupied is 
reused as stack space. When TeamRoot() returns, _start calls ma1n(), the main function of the C 
program being executed. Finally, if main( ) ever returns, _start calls ©x1t( ) with the value returned by 
ma1n(). 
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The V-System Configuration Database 

The V-System maintains a configuration database, containing information about each workstation. The 
information is organized as sets of keyword/value pairs, one set per workstation. 

19.1 . Querying the Database 

There is one standard library function provided for extracting information from the configuration database: 



SystemCode QueryWorkstat1onConf1g(keyword, value, max length) 
char •keyword, *va1ue; 
1nt maxlength; 

Given a character string representing the keyword, this routine returns the corresponding value as another 
character string. The variable keyword points to the keyword, value points to the place to put the value, 
and maxl ength is the size of the buffer, which should include space for a terminating null byte. The routine 
returns a system error code if there is no configuration information recorded for the querying workstation 
(NOT_FOUND), there is some configuration information, but no value corresponding to the given keyword 
(BADlARGS), or the buffer was too short to hold the value (BAD.BUFFER), else returning OK. In the 
buffcr-too-short case, it will return as much as there is room for. In unusual situations, other error codes may 
be generated; these can be treated as failures or considered equivalent to NOT_FOUND. 

19.2. Currently Defined Keywords 

The following keywords arc in use at this writing. A list of keyword names and their meanings is presently 
kept in the same directory as the config files themselves, in a file called "keywords." 

name The name of this workstation. Should match the name used in local IP name tables for this 

workstation's IP address. There is no default. 

alt-cthcr-addr Alternate cthcrnct addresses for this workstation, one per line. These arc addresses the 
workstation may use, other than the one the config file is named for. 10 Mbit addresses 
should be given in hexadecimal, in the form xxxx.yyyy.zzzz. 3 Mbit addresses may be 
given in octal. The default is null. This keyword must be present for use by the Vax Unix 
ND server for workstations that boot using the ND protocol under a different Ethernet 
address than the one the config file is named for. This is true of SMI Sun-2's with PROM 
revision N or later and 3Com Ethernet interfaces. 

bootfile File to be loaded by ndscrvcr or mvaxbootscrvcr. Defaults to compilcd-in 

/usr/V/boot/VloadlO.d or /usr/V/boot/V load. vax respectively. llic former is 
appropriate for a Sun-2 or Sun-1.5 with 3Com Ethernet interface. Should be an absolute 
pathname. 

ip-addrcss The workstation's Internet Protocol address, given in the conventional [a.b.c.d] notation, 

where a, b, c, and d arc decimal integers. On the 3 Mbit Ethernet, the default value of d is 
the 8-bit Kdicmct host address, while default values of a, b, and c arc determined by the 
Internet server. For the 10 Mbit Ethernet, this keyword should always be present 
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ip-gatcways Name of a file containing a list of Internet gateways to be used by this workstation. The 

file name is given relative to the standard [sys] context If this keyword is omitted, the 
Internet server will not forward datagrams through any gateways, i.e., only local traffic will 
be supported. 

boot Controls whether the boot server (ndservcr for Sun Network Disk protocol, 

mvaxbootscrvcr for Micro VAXes with DEC MOP protocol) will respond to boot requests 
from this workstation. The server will refuse to respond only if there is no config file 
(although mvaxbootscrver has a "-n" flag to override this) or if the config file contains 
"boor.no". This field has no effect on Sun-3 RARP/TFTP booting. 

ndboot A synonym for "boot", used only by the ndserver. This is an historical relic and should 

vanish in the future. Any existing config files which use "ndboot" should be edited to use 
"boot". 

kernel Filename of the program to be loaded as the kernel, for use by Vload. The name is given 

relative to the standard [sysjboot context If this keyword is omitted, Vload uses a 
compilcd-in default 

team Filename of the first team, as above. If it is omitted, Vload uses a compilcd-in default 

currently teaml-vgts. 

world Either V or xV. Used by Vload. If omitted, Vload uses a compilcd-in default currently V. 

boot-options Boot options for use by Vload. Currently the only option is b, meaning "break before 
starting kernel" The default is a null string. 

startup-script Filename of the startup script Currently used only by tcaml-scrver, for workstations that 
autoboot as servers. No default In the future, the definition of this keyword will be 
changed to allow the startup script to be placed directly in the config file, and all (or most) 
versions of the first team will use it This feature is not in V6.0. 

terminal-type Type of terminal used as a console. Used by the STS. The default is to assume the 
Stanford PROM terminal emulator for Cadlincs, or something ANSI -compatible (like the 
SMI PROM terminal emulator) otherwise. The only other recognized value for this option 
is"hl9". 

location Optional location field. 

comment Used to put a comment in the file, such as a description of the workstation. 

19.3. Implementation 

Ordinarily, programs should not be aware of the implementation of the configuration database; this 
implementation may change in the future. The Query WorkstationConflgO function should be the only 
interface used. Since there is no standard library function provided to modify the configuration database, 
however, system maintaincrs need to be aware of its implementation. 'ITic current implementation allows the 
configuration database to be modified with an ordinary text editor, and the changes installed with the same 
tools thai arc used for instilling new binary program images on storage servers. 

The V configuration database is currently implemented as a set of configuration files, one for each 
workstation. Each configuration file must be present on every publically-availablc V storage server. 

The name of each workstation's configuration file is derived from its hardware Ethernet address (a 



Publically-availablc storage servers arc defined as those that respond to GctPid(S10RAGO_SERVI:R. ANYJMD) requests from 
nonlocal clients. 
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convenient unique identifier). 10 The files are kept in a subcontext named "config", under the server's [sys] 
context For a workstation with Ethernet address 0260.8c01.9954 (a typical 3Com-assigncd address), the 
configuration file could then be read by a workstation as a file named 41 [sys]config/C.02608cO 19954"; this is in 
fact how QueryWorkstationConfigO is implemented. 

A configuration file is an ASCII text file, consisting of a set of key word/ value pairs, arranged in no 
particular order. Each keyword appears at the beginning of a new line, and is separated from its 
corresponding value by a colon (':'). A line beginning with a colon serves as a continuation of the value on 
the previous line. This format has been designed to be easy to read and easy to parse. (Note that spaces both 
before and after the colon may be considered significant by programs, so take care when creating or editing 
config files.) 

At Stanford, the master copies of configuration files are kept in the directory /xV/config on Pescadcro, and 
only those copies should be edited. The command "build install" (run as user ds) is used to install changes. 

19.4. Usage 

In general, we have implemented programs that use this service in such a way that if a configuration file or 
specific keyword/value pair is missing, some reasonable default is used where this is possible. Also, where it 
is easy to reliably determine something by examining the hardware present, it is best to do that instead of 
putting the information in the configuration file. Following these principles means that fewer updates to the 
configuration files arc needed to keep workstations running correctly when something changes. 

In some cases, the value of a keyword may be the name of a file, perhaps because it is more convenient for 
the client to read the information from a file, or because the information associated with the keyword is quite 
bulky. In the present implementation, such files arc kept in the "[sys]config" directory along with the 
configuration files themselves. Files whose names begin with "S." are startup command scripts for 
workstations that boot automatically. Files whose names begin with "G." arc gateway information files used 
by the internet server. 



^Currently, on Sun-2 workstations with 3Com F.thcrnct interfaces, the address assigned to the Ethernet board is used, not the address 
assigned to the processor. 
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Instances of the V executive, or command interpreter, are normally created and controlled directly by the 
user interacting with the system. However, this control is also available to programs through the following 
functions: 



1nt CreateExec(execserver, Inserver, 1nf11e, outserver, outflle, 
errserver, errflle, cpld, edd, flags, execpld, 
error) 

Processld execserver; 

Processld Inserver, outserver, errserver; 

Instanceld 1nf1le, outflle, errflle; 

Processld cpld; 

Contextld odd; 

short flags; 

Processld *execp1d; 

SystemCode *error; 

Create an instance of the executive with the specified standard input, standard output, standard error output, 
and context. Each of die three standard i/o files is specified by two parameters, the server pid and the 
instance identifier within that server. This means that all these instances must be opened before Create 
Exec is called. Context is specified by two parameters, a server pid and a context identifier relative to the 
given pid. The GetContextld function will map a context name into such a pair. Execserver is the pid 
of the exec server to which the request is being made. ITic Flags parameter determines which if any of the 
standard i/o instances arc to be owned by the newly created executive; it may be any combination of 
RKLKASKJNPUT, RKLKASI-LOUTPUT, and RRI.KASH.KRR. If for example RHLKASKJNPUT is 
specified, ihc executive will own its standard input instance and will release it on termination. 

CreateExec returns an exec identifier, a small integer which will be used to refer to this executive in other 
executive control requests. In the location pointed to by execpld it returns the process id of the new 
executive. In the location pointed to by error it returns a system error code; if this code is not OK, the exec 
identifier and execpid arc meaningless. 

WARNING: a server process cannot call CreateExec with a file instance pointing to that server itself, or 
the server and the execserver will become deadlocked waiting for each other. A server that needs to do this 
should create a subproccss to call CreateExec . 



SystemCode DeleteExec(execserver, exec Id) 
Processld execserver; 
int exedd; 

Delete the executive specified by exedd, along with the program running under it if any. It need not have 
been created by this process: there is no concept of ownership of execs. Note that this is not the only way 
executives vanish; they also terminate on end of file on the standard input DeleteExec will return 
NOTJ-'OUND if exedd is invalid. 
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SystemCode QueryExec(execserver, exedd) 
Processld execserver; 
1nt exedd; 

Inquire about the state of the specified exec. If successful, it returns a code of OK, and the following 
information: in execpld the process id of the exec; in program, the process id of the program running 
under it, if any; in status, the status of the exec. Status can be one of 

EXEC_FREE Exec is waiting for a command. 

EXEC_LOADING 

exec is in the process of loading a program. 

EXEC.RUNNING 

A program is running under this exec. In this case and this case only, program returns 
relevant information. 

EXEC_HOLD Exec has been created but not yet started. Hopefully this state should never be observed, 
as it is taken care of within CreateExec. 



SystemCode K111Program(execserver t exedd) 
Processld execserver; 
1nt exedd; 

Kill the program, if any, running under the specified exec. Returns OK is successful, NOT.FOUND if 
execid was invalid, NONEXISTENT^PROCESS if there was no program running under that exec. 



SystemCode CheckExecs(execserver) 
Processld execserver; 

Causes the execserver to do a check on all executives. Any of them whose standard input server or standard 
output server (but not standard error server) has died is destroyed during the check. This should be called 
after an action that might have destroyed an i/o server which was providing standard i/o for one or more 
executives. 
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Fields: Using an AVT as a Menu 



These routines allow you to set up a table of fields in an AVT. They can be selected with the mouse, so that 
you can have a menu. The advantages over the standard pop-up menu are that you can have more choices, 
you can display more information with each choice, and the menu is always there. 

With each field, you can associate a value, which can be displayed and edited. 
The menu is an array of F 1 e 1 ds. These are defined in <f 1 e 1 ds . h>. Each Field consists of: 
typedef struct 

short row; /* field's row number in AVT •/ 

short col; /* leftmost character of field */ 

short width; /* width of field */ 

long *value; 

1nt (*proc)(); 

char •format; /* format in which to display *value */ 

} Field; 
row and col indicate where in the AVT the field begins. (row=l and col=l is the top left corner of the 
AVT.) width is the length of the field in characters. Only one-line fields are supported, proc is not used 
by the package itself. The intended usage is: 

field - 6etField(...); 

1f (field) (*f1eld->proc))(field->value); 

or perhaps: 

1f (field) (*f1eld->proc))(f1eld); 

format is discussed below. 

21.1. Formats 

format is a format like those used by pMntf and scanf. Together with the value, it determines the 
string to be displayed in the field. This string must be a least w1 dth characters long. It is a zero-terminated C 
(asciz) string. Formats arc of the form: 

prefix [conversion] suffix 
Here prefix and suffix is constant text which is displayed. If a % is to be displayed, it must be written as %%. 
The following utility routine will do a string copy analogous to strncpy, except that %s arc automatically 
copied: 



char • StrToFormat(f, s, n) 

char *f; /* destination string buffer where Ts arc to be doubled •/ 
char *s; /• source string */ 
1nt n; /* count - buffer size */ 

The optional conversion describes how value is to be displayed/read. Its form is: 

%[[-][Q]ficldwhlth][.prccision][\]c 

Here the X indicates the beginning of the conversion specification. The conversion type letter c marks the end 
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of the conversion specification. 'Hie format is exactly as used by prlntf , except that there may be a data 
length specification \. If value is a short • rather than a 1nt •, X must be given as h. Ifthe value isa 
doubl e • rather than a f 1 oat *, X must be 1 , or the conversion type letter c must be capitalized. 

When fields are displayed, sprlntf is used to do the conversion. The length specification X is only used 
to dereference value (except for fields where the conversion type letter is s); it is stripped from the format 
before being passed to spr 1 ntf. 

On input to fields, only the length specification X and the type code c are passed to sscanf. Ifthe type 
code is e or g, it is changed to f . A type code of S (or 1 s) means that the whole input line (including spaces) 
should be accepted. 

21 .2. The Field Table as a Menu: Selecting an Action 

Field * GetF1eld(menu, menuLength, buttons, avt) 

Field *menu; 

1nt menuLength; 

short buttons; 

File *avt; /• output AVT */ 

If button I ■ 0, it is assumed that the mouse is down on procedure entry. GetField returns when the 
button state changes; if it changes to non-zero, GetField fails by returning zero. If button — 0, 
GetFlel d will first wait for an event (It will fail unless it is a mouse button being pressed down.) 

As long as the user keeps the mouse button down, display the selected field (if any) in inverse video. When 
the user releases the button, return the last selected F 1 e 1 d, or if none, return 0. 

The menu is terminated by the first negative row field, or when the menuLength count is exhausted. 

21 .3. Displaying Fields 



PutF1eld(buffer, field) 

char *buffer; /• destination string buffer •/ 
Field •field; /* source format and value */ 

More or less like sprlntf (buffer, f1eld->format, »f1eld->value). 

D1splayF1elds(menu, menuLength, avt) 
Field *menu; 

1nt menuLength; /* see GetField function •/ 
File *avt; /• output AVT where fields are to be written •/ 

Display in the avt all the string fields, at the positions given by the row and col components. 

The width components arc ignored. 'ITiis allows convenient display of material which the user cannot 
select ("writc-protcctcd" fields) cither by using fields with w1 dth <■ or by having a s tr 1 ng longer than 
the width. 

21 .4. User Input to Fields 
Ed1tF1eld(f1eld, stuff, out. 1n) 
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Field *f1eld; /• field whose * value is to be edited */ 

1nt stuff; /• 0: old text should be cleared: 1: stuff into editor */ 

File *out, *1n; /• input and output sides ofAVT to use •/ 

Move the cursor to the conversion part of the field. If stuff is 0,'the old value is cleared from the screen; 
if it is I, the old value is placed in the line editing buffer. Enter line-edit mode, and wait for the user to type 
in a line. If the user types tG, abort, redisplay old value and return -1. Else parse the line using 
f1eld->format. If this succeeds, update *f1eld->value, returning 1, else 0. In any case, redisplay 
things correctly. 



Ed1tStdFld(f1eld) 

Equivalent to Ed1tF1eld(f1eld, 1, stdout, stdln) 

ReadStdFld(fleld) 

Equivalents Ed1tF1eld(f1eld, 0, stdout, stdln) 

21.5. An Example 

/* This 1s a program which adds up Integers, optionally scaled */ 

JHnclude <std1o.h> 

#1nclude <f1elds.h» 

double Scale ■ 1.0, Total ■ 0.0; 

1nt Value - 0; 

Qu1t() { ... cleanup actions ...; ex1t(-l);} 

NewValue(f) 
Field *f; 

{ 

1f (ReadStdFld(f) « 1) 
Total +■ Value * Scale; 
} 
Fields Menu£] ■ 

{ 
/* VAL (defined 1n fields. h) coerces pointers and values to (1nt *) */ 

{1. 41, 10, VAL &Seale. EdUStdFld. "Scale: XG "}, 

{1, 1. 15, VAL &Value. NewValue, "New value: X-8d"}, 

{2. 1, 0, VAL SJotal. 0, "Total: %G. "}, 

{5, 1. 8, 0, Quit. "—Quit—"}. 
LASTFIELD /* defined 1n fields. h •/ 
}: 

ma1n() 

{ Field *f1eld; 
while (1) 

{ 

putc(*L' & 31, stdout): /* write FormFeed to clear screen */ 

DisplayF1elds(Menu. 999, stdout); 

field - GetF1eld(Menu. 999, 0. stdout); 

1f (field) (*(f1eld->proc)) (field); 
} 
> 

Since the screen is updated every time here, we do not have to worry about garbage being left behind when 
the field becomes shorter. However, one of two fixes shown above can be used when this is not desired: In 
the Val ue field, we make sure the field doesn't become shorter, by Icil justification if needed. 'Hiis loses if we 
want to output punctuation after Uic value, as in the Total field. In this case,, we can make sure that we 
output enough trailing spaces to erase the garbage. 
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21.6. Limitations 

No facilities yet for arrays. 
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Input and Output 



The input and output routines can be divided into three categories: 

1. Basic I/O routines like get chap () that are supported but differ in their implementation from the 
standard Unix versions. 

2. I/O support routines like pr1 ntf ( ) that are identical with the standard Unix version. 

3. V-specific I/O routines like Road() and Wr1te() that are used in several cases to implement the 
standard C routines in the V message-based world. 



22.1 . Standard C I/O Routines 



The following standard C I/O routines are available: 



clearerr() 

ferror() 

fopen( ) 

fread() 

ftell() 

gets() 

printf() 

putw() 

scanf () 

sscanf( ) 



closodir() 

fflush() 

fpp1ntf() 

freopen() 

fwp1ite() 

getw() 

putcf) 

peaddip() 

spr1ntf() 

telldip() 



fclose() 

fgetc() 

fputc() 

f scanf () 

getc() 

mkteop( ) 

putchar() 

rewind( ) 

seekdir() 

ungetc() 



feof() 

fgets() 

fputs() 

fseek() 

getchar() 

opendir( ) 

puts() 

pewindd1p() 

setbuf() 



However, f open( ) returns a pointer value of type *Filc, where File is defined in <Vio.h> and is a totally 
different record structure from that used by, for instance, the Unix standard I/O. Also, setbuf ( ) is a no-op 
under V. 

22.2. V I/O Conventions 

Program input and output arc provided on files, which may include disk files, pipes, mail-boxes, terminals, 
program memory, printers, and other devices. 

To operate on a file, it is first "opened" using Open( ) if the file is specified by a pathname, otherwise by 
OpanF i le( ) if the file is specified by a server and instance identifier. The mode is one of the following: 

KRKAD No write operations arc allowed. File remains unchanged. 

FCREATE Any data previously associated with the described file is to be ignored and a new file is to 

be created. IJoth read and write operations may be allowed, depending on the file type 
described below. 

FAPPEND Data previously associated with the described file is to remain unchanged. Write 

operations arc required only to append data to the existing data. 

FMODIFY Existing data is to be modified and possibly appended to. Both read and write operations 

arc allowed. 
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Both open functions return a pointer to an open file descriptor that is used to specify the file for subsequent 

operations. CI ose( ) removes access to the file. Seek( ) provides random access to the byte positions in the 

file. Note: the value returned from a byte position that has not been written is not defined. 

* # 

Each program is executed with standard input, output and error output files, referred to as stdln, 

stdout, and stderr respectively. 

The file type indicates the operations that may be performed on the open file as well as the semantics of 
these operations. The file type is specified as some combination of the following attributes. 

READABLE The file can be read. 

WRITEABLE The file can be written. 

APPEND.ONLY 

Only bytes after the last byte of the data previously associated with the file can be written. 

STREAM All reading or writing is strictly sequential. No seeking is allowed. A file instance without 

the STREAM attribute must store its associated data for non-sequential access. 

FIXED.LENGTH 

The file instance is fixed in length. Otherwise the file instance grows to accommodate the 
data written, or the length of the file instance is not known as in the case of terminal input 

VARIABLE.BLOCK 

Blocks shorter than the full block size may be returned in response to read operations other 
than due to end-of-file or other exception conditions. For example, input frames from a 
communication line may differ in length under normal conditions. 

With a file instance that is VARIABLE.BLOCK, WRITEABLE, and not STREAM, 
blocks that arc written with less than a full block size number of bytes return exacdy the 
amount written when read subsequently. 

MULTI.BLOCK Read and write operations arc allowed that specify a number of bytes larger than the block 
size. 

INTERACTIVE The open file is a text-oriented stream. It also has the connotation of supplying 
interactively (human) generated input 

Not all of the possible combinations of attributes yield a useful file type. 

Files may also be used in a block-oriented mode by specifying l ; BLOCK_MODE as part of the mode when 
opening the file. No byte-oriented operations arc allowed on a file opened in block mode. 

Sec chapter 33 for more details on the semantics of the various possible file types and modes. 

22.3. V I/O Routines 
22.3.1. Opening Files 



File *Open( pathname, mode, error) 

char •pathname; unsigned short mode; SystemCode *error; 

Open the file specified by pathname with the specified mode and return a file pointer for use with 
subsequent file operations. 

mode must be one of FREAD, FCREATE, FAPPENO, or FMODIFY, with FBLOCK.MODE if block 
mode is required. If Open() fails to open the file, it returns NULL and the location pointed to by error 
contains a standard system reply code indicating the reason. If an error occurs and error is Num Open( ) 
calls abort(). 
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File *OpenDuplex(f1le, mode, error) 

File *f11e; unsigned short mode; SystemCode *error; 

Open the "other side" of a duplex file, such as a network connection or terminal. Mode and error are as in 
Opeh(). 

File •OpenF1le(serveir, 1nstance1dent1f1er, mode, error) 
Processld server; Instanceld 1nstance1dent1f1er; 
unsigned short mode; SystemCode *error; 

Open the file instance specified by the server and 1nstance1dent1f 1er arguments and return a file 
pointer to be used with subsequent file operations. 

mode must be one of FREAD, FCREATE, FAPPEND, or FMODIFY, with FBLOCKJvlODE if block 
mode is required. If the instance is to be released when C1ose() is called on this file pointer, 
FRELEASE_ON_CLOSE must also be specified as part of the mode. If OpenFI 1 e ( ) fails to open the file, 
it returns null and the location pointed to by error contains a standard system reply code indicating the 
reason. If an error occurs and error is null, OpenFI le( ) calls abort ( ). 



File <\_0pen(req, mode, server, error) 

CreatelnstanceRequest *req; unsigned short mode; 
Processld server; SystemCode *error; 

Open a file by sending the specified I/O protocol request message req to the server specified by server and 
return a file pointer to be used with subsequent file operations. This function is only used when additional 
server-dependent information must be passed in the request message, or the file is to be opened on a server 
that cannot be specified by a character string pathname as in Open( ). 

The request req may be either a CreatelnstanceRequest or a QuerylnstanceRcqucsL mode must be one of 
FREAD, FCREATE FAPPEND, or FMODIFY, with FBLOCK_MODE if block mode is required. If 
_0pen( ) fails to open the file, it returns null and the location pointed to by error contains a standard 
system reply code indicating the reason. If an error occurs and error is null, _0pen( ) calls abort ( ). 



Processld Createlnstance(pathname, mode, req) 

char 'pathname; unsigned short mode; CreatelnstanceRequest *req; 

Open the file specified by pathname in the given mode using the specified CreatelnstanceRequest, but do 
not set up a File structure for it A CrcatclnstanccRcply is returned at the location pointed to by req. The 
function returns the process id of die first process that replied. If the create instance request was sent to a 
group, additional replies can be obtained using GetReply ( ). 

SystemCode Create0up1exlnstance(server, 1d, mode, req) 

Processld server; Instanceld 1d; unsigned short mode; 
CreateDuplexInstanceRequest req; 

Open the "other side" of the file specified by the server and 1d, but do not set up a File structure for it A 
CrcatcDuplcxInstanccRcply is returned at the location pointed to by req. Return a standard system reply 
code. 

22.3.2. Closing Files 
Close(fHe) 
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File •Hie; 

Remove access to the specified file, and free the storage allocated for the File structure and associated buffers. 
If the file is WRITEABLE and not in FBLOCKJvIODE, the output buffer is flushed. 



Spec1alClose(f1le, releasemode) 

File *f11e; unsigned releasemode; 

Gose the specified file, as in Close( ). If Spec1alClose() releases the file instance associated with the 
specified File structure, the release mode will be set to releasemode. Close( ) sets the release mode to 
zero. Sec chapter 33 for a explanation of release modes. 



Releaselnstance(f1leserver, flleld, releasemode) 

Processld fUeserver; Instanceld flleld; unsigned releasemode; 

Gose the file instance specified by flleserver and flleld, using the specified release mode. This 
function is used only when there is no File structure for the given fUe. 

22.3.3. Byte Mode Ope rations 

The purpose of the byte-mode I/O library is to maintain an abstract view of a file instance as an array of 
bytes with a known (but extensible) length, and the ability to read, write, and (in the case of non-STREAMs) 
seek, at the byte level. A layer of buffering is imposed between the client and server maintaining the actual 
file instance, to reduce the amount of actual reading and writing done. The actual file instance is guaranteed 
to be identical with the local view when the file is first opened, and after a Flush, barring I/O errors. (Note 
that Close calls Flush before releasing the instance.) At most one block of the local view of the file instance 
may differ from the actual instance. 

The I/O library can be used on any file type, though somewhat confusing results may be obtained with 
VARIABLE- BLOCK, non-STREAM files, particularly if one attempts to Seek in other than ABS- BLOCK 
mode. 

The standard Unix functions mentioned above may be used on files opened in byte mode (i.e., not opened 
in FBLOCKJvIODE). Several other functions arc also available on such files, as described below. 



1nt Seek(f1le, offset, origin) 

File *f1le; 1nt offset, origin; 

Set the current byte position of the specified open file to that specified by offset and origin and return 
TRUE (nonzero) if successful. 

If origin is ABS_BLK or ABSJWTE, the byte position is set to the off set-th block or byte in the file 
starting from 0. If origin is RKLJWTR, off set specifics a signed offset relative to the current byte 
position. If origin is FILEJ'NI), offset is the signed byte offset from the end of file. 

The end of file position is one beyond the last byte written. 'Hie value of bytes in the file previous to the 
end of file that have not been explicitly written is undefined. 

Seek( ) may not be used on files opened in block mode. SeekBlock( ) should be used on such files. 
Seek( ) is identical to f seek( ). 

unsigned BytePos1t1on(f1le) 
File *f1le; 

Return the current byte position in the specified file. The value returned is correct only if die current byte 
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position is less than MAXJJNSIGNED. This function is identical to f tell ( ). 



Flush(flle) 
File »fne; 

Flush any buffered data associated with the file, providing it is WRITEABLE Flushing a file causes local 
buffered changes to the file data to be communicated to the real file. If the file is in block mode or not 
WRITEABLE, no action is performed. This function is identical to f f 1 ush( ). 



Resynch(fHe) 
File •file; 

Identical to ClearEof ( ). 

SystemCode Eof(fHe) 
File •file; 

Any of the byte mode read or write operations may return EOF (Exception On File) as a special value 
indicating an inability to read or write further in the file. Eof() returns a standard system reply code 
indicating the nature of the exception. This may be a true end-of-file, i.c„ the current byte position exceeds 
the last byte position of the file, or some type of error. 

ClearEof(fHe) 
File •tile; 

Clear the local record of the last exception on the given file, and rcsynchronize the local view of the associated 
file instance with that of the server, including the size of the file and (for STREAMS) the next block to read. 
This function only clears the local record of the exception; it docs not affect the circumstances that caused the 
exception to occur. Sec Eof ( ). 

If the file is not of type STREAM, trie contents of the local buffer arc discarded even if the buffer was 
modified and not yet rewritten. If the file is of type STREAM, and the current file position violates the 
stream condition (always read nextblock or write lastblock+1), reposition. The contents of the local 
buffer arc discarded only if repositioning is necessary. 



1nt BufferEmpty(flle) 
File *f1le; 

Test whether or not a file's local buffer is empty. If this function returns TRUE (nonzero), the next getc( ) 
will cause an actual read. If it returns FALSE (zero), the next getc( ) will return immediately with a byte 
from the buffer. 

22.3.4. Block Mode Operations 

The following functions arc most useful on files opened in block mode. Unless otherwise noted, they may 
also be used on files opened in byte mode. 

unsigned Read(f11e, buffer, bytes) 

File *f1le; char 'buffer; unsigned bytes; 

Read the specified number of bytes from the file starting at the beginning of the current block location of the 
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file and store contiguously into the byte array starting at buffer, returning the actual number of bytes read. 

The number of bytes returned may be less than the number requested if (I) the file has the type attribute 
VARIABLE.BLOCK and a short block was being wad, (2) end of file was encountered while reading, (3) an 
error occurred while reading (in this case bytes arc returned), or (4) more than one block was requested and 
either the file docs not have the type attribute MULTIJJLOCK, or the server could not return as many 
blocks as were requested. If the read request cannot be satisfied, the reason is indicated by the standard reply 
code returned by F1leExcept1on(). If the end of file is encountered while reading, a partial block is 
returned with the reply code END_OF_FlLE. Read( ) is intended for use on files opened in block mode 
only. Note: Read( ) does not increment the current block number stored in the File structure for the given 
file. 



unsigned Wr1te(f1le, buffer, bytes) 

File •file; char *buffer; unsigned bytes; 

Write the specified number of contiguous bytes from the buffer to the file starting at the beginning of the 
current block location of the file, and return the actual number of bytes written. 

The number of bytes to be written must be less than or equal to the block size (as returned by 
Bl ockS1ze( )) unless the file has the type attribute MULTIJJLOCK. If the number of bytes written is less 
than the number of bytes requested, the reason is indicated by the standard reply code returned by 
F11eExcept1on(). 

Wr1te( ) should be used only on files opened in block mode. Note: Wr1te( ) does not increment the 
current block number stored in the File structure for the given file. 



unsigned B1ksInF11e(f11e) 
File *f1le; 

Return the number of blocks in the specified file. If the number of blocks is unknown, MAXUNSIGNED is 
returned. 



unsigned B1ockPos1t1on(f11e) 
File «f1le; 

Return the current block position in the specified file. 



SeekB1ock(f11e, offset, origin) 

File *f1le; 1nt offset; 1nt origin; 

Set the current block position of the specified open file to that specified by origin and offset. The new 
block position is the block offset from the specified block origin, origin is one of FILEJiKG INNING, 
1'II.E FND or FII.K.OJRRF.NTJ'OS. 



unsigned B1ockS1ze(f1le) 
File •file; 

Return the block size in bytes of the specified file. 



unsigned F1leExcept1on(f 1le) 
File «f11e; 
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Return the standard reply code indicating the last exception incurred on the specified file. This is used 
primarily on files opened in FBLOCK_MODE Eof ( ) is used on byte-oriented files. 

22.3.5. Server-Specific Operations 

This section describes routines in the I/O library which arc specific to particular servers. 



SystemCode CreateP1peInstance(read0wner, wHteOwner, buffers, reply) 
Processld readOwner, wrlteOwner; 1nt buffers; 
CreatelnstanceReply •reply; 

Interact with the pipe server to create a pipe, with the specified owners for the reading and writing ends of the 
pipe, and the specified number of buffers, buffers should be between 2 and 10 inclusive. The reply to the 
create instance request is returned at the location pointed to by reply; it contains the file instance id of the 
writcable end of the pipe. The id of the readable end is equal to this value plus 1. OpenFI le( ) may be used 
to set up File structures for either or both ends of the pipe. CreateP1peInstance( ) returns a standard 
system reply code, which will be OK if the operation was successful 



File •OpenTcp(localPort, forelgnPort, forelgnHost, active, 
precedence, security, error) 
unsigned short localPort, forelgnPort; unsigned long forelgnHost; 
1nt active, precedence, security; SystemCode *error; 

Interact with the Internet server to create a TCP network instance, and return a pointer to a File structure 
opened in byte mode that can be used to send data on the corresponding TCP connection. 

To obtain a second File structure that can be used to read from the connection, use the call 
f2 - 0penF1le(FneServer(fl), FHeld(fl) + 1, 
FREAD + FRELEASE_ONj:LOSE, &error) 

where f 1 is the value returned by OpenTcp( ). Note that it is necessary to release both the readable and 
writcable instances to cause the connection to be deallocated. Releasing the writcable instance closes the 
caller's end of the connection. Data can still be read from the readable instance until it is released, or the 
other end closes (resulting in an KN1)_0F_FILK indication). 

The parameters local Port, forelgnPort, and forelgnHost specify the sockets on which die TCP 
connection is to be opened, active specifies whether the connection should be active (i.e., send a 
connection "syn" packet), or passive (i.e., listen for an incoming *'syn" packet), precedence and 
security specify the precedence and security values to be used for die connection. Specifying zero for 
these parameters will cause appropriate default values to be used. 

If the open is unsuccessful, OpenTcp() returns null, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 



File *0penlp(protocol, error) 

char protocol; SystemCode *error; 

Interact with the Internet server to create an IP network instance, and return a pointer to a File structure 
opened in block mode Uiat can be used to write IP packets to the network. 

To obtain a second File structure that can be used to read IP packets, use the call 
f2 - 0penF1le(F1leServer(fl), Fileld(fl) + 1, 

FREAD + FBL0CK_M0DE + FRELEASE_ONj:LOSE , &error) 

where fl is the value returned by 0penlp(). Note that it is necessary to release both the readable and 
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writcablc instances even if only one of them is used. 

The protocol specifies which value of the protocol field in the IP packet headers is of interest. The 
readable instance will only return packets with the requested protocol value, and the client program should 
only write packets with the specified protocol field to the writcable instance, though this is not currently 
checked by the server. If protocol is zero, it specifies "promiscuous" mode, in which all IP packets are 
returned which are not of protocol types that have been requested by another client, and packets of any 
protocol type may be written. 

If the open is unsuccessful, 0penlp() returns NULL, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 

22.3.6. Miscellaneous I/O Functions 

Instanceld F1leld(f1le) 

File *f1le; 
Return the file instance identifier associated with the open file. This was either generated as part of Open ( ) 
or specified as an argument tothc0penF1le() operation that opened the file. 

Processld F1leServer(f1le) 
File •file; 

Return the file server identifier associated with the open file. This was cither generated as part of Open ( ) or 
specified as an argument tothc0penF1le() operation that opened the file. 



unsigned F1leType(f1le) 
File *f1le; 

Return the file type, which indicates the operations that may be performed on the open file as well as the 
semantics of these operations. 



unsigned Interact1ve(f1le) 

File *f11e; 
Return TRUE (nonzero) if the file has the type attribute INTERACTIVE, else FALSE (zero). 

File •OpenStrfstr, size, error) 

unsigned char *str; unsigned size; SystemCode »error; 

Make the specified string look like a file. The file is FIXED.LKNGTH, with one block of size size, and the 
end of file set to the end of this block, str must point to an area ;it least s1 ze bytes in length. A file opened 
by OpenStr( ) is identified as such by its file server (as returned by F1 leServer ( )) being equal to 0. 

SystemCode RemoveF1le( pathname) 
char 'pathname; 

Remove (delete) the file specified by pathname. 



1nt unllnk(pathname) 
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char 'pathname; 

Remove (delete) the file specified by pathname. Returns on success, -1 on failure. This interface is 
provided for UNIX compatibility. 



SystemCode SetBreakProcess(f1le, breakprocess) 
File *f1le; Processld breakprocess; 

Sets the break process associated with the specified file (which must be INTERACTIVE) to breakprocess. 
If a break occurs on the file after a break process has been set, the IO_BREAK reply will be returned to any 
outstanding read requests, and the specified break process will be destroyed. 



SystemCode Setlnstance0wner(f1leserver, flleld, owner) 
Processld flleserver, owner; Instanceld flleld; 

Set the owner of the specified file instance to be owner. 



Pr1ntF11e(name ( file) 

char *name; File *f11es 

Print the value of each field in the given File structure on the standard output, identifying the file by the 
name name. Useful in debugging servers and I/O routines. 

22.4. Portable binary integer I/O 

The following routines can be used to write and read integers to a file in a standard binary representation. 
This representation stores integers in 1, 2, 3, or 4 bytes, signed or unsigned. The integers arc written as binary 
numbers, 8 bits to a byte, in big-endian order. For the signed routines, twos-complement is used. (This 
convention is followed by a number of systems, including files read and written by TcX and METAFONT.) 

The subroutines are declared as follows, for N = 1, 2, 3, and 4: 



PutS1gned;V(1, f) 
long 1; File *t 



PutUns1gnedW(1. f) 
long 1; File *fi 



long GetSigned/V(f ) 
File *f; 



long GetUnslgnedJV(f) 
File *f; 
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Intra-Team Locking 



The V kernel provides message-passing as a means of synchronizing processes, and mutual exclusion may be 
enforced by the use of a server process that executes the critical section for clients. Such an arrangement is 
not always suitable, however: for processes communicating via a shared data structure the overhead of a 
message exchange may exceed by an order of magnitude the cost of performing the critical section. 

The V library includes support for cheap mutual exclusion among processes in a single team. Spin locks 
ensure mutual exclusion in me presence of contention, but in its absence they introduce very little overhead. 
Spin locks also maintain a count indicating the level of contention so that the programmer can continue to 
assess their suitability after they are in use. 

Spin locks are essentially binary semaphores without qucucing: when a process fails in an attempt to 
acquire a lock, it simply delays (instead of busy-waiting) before trying again ("spinning" the lock). 

Advantages: In the absence of contention, spin locks arc fast. The optimized macro forms require only 
from one to six machine instructions each; the procedure forms add only the cost of a single-argument 
procedure call. 

Disadvantages: A process that fails in an attempt to acquire a lock delays one tick before trying again; the 
locking overhead in the presence of contention is therefore higher than it would be for a message exchange 
with a server process. Also, spin locks are not fair: the order in which processes acquire the lock is not 
detcrminca by the order in which they begin their attempts. 

Spin locks are best suited for cases in which contention is expected to occur only rarely. The repeated 
attempts at the lock render them less suitable when the lock is held for long periods of time (several clicks), 
and the delay period (one click) may be too long for some applications with real-time constraints. 

Each spin lock maintains a contention count, incremented each time that a process is forced to delay in an 
attempt to acquire the lock. The counter is incremented without mutual exclusion; its value is therefore not 
guaranteed precise, but should still provide a rough indication of the level of contention. 

The following subroutines arc provided in the library, with needed definitions in Vspinlock.h. 



Acqu1reSp1nLock(1ock) 
SplnLockType *lock; 

Wait until the named lock is acquired before returning. The delay on failure is one click. 



ReleaseSplnLock(lock) 
SplnLockType *lock; 

Release the named lock. 

Additionally, the macro SplnLockCount(lock) provides access to die contention count; it is of type 
short Integer and may be assigned to as well as read. 

Locks must be initialized to cither SplnLockLocked or SplnLockUnlocked, which also set the 
contention count to zero. 

More efficient macro forms of the locking operations arc provided for the common cases of the lock being a 
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global variable or an argument to the procedure invoking the operation. The costs of these forms of the 
operations are in the range of one to six machine instructions. The compiler and lint, however, cannot 
properly check theses forms, which may result in cither spurious error messages or failure to detect real errors. 



Acquired obalSplnLock(lockName) 
SplnLockType lockName; 

Equivalent to Acqu1reSp1nLock(&lockName), where lockName is the name of a global (extern) 
variable. (This will also work if the global variable 1 ockName is a struct and the lock is its first component.) 



ReleaseGlobalSp1nLock( lockName) 
SplnLockType lockName; 

Equivalent to ReleaseSp1nLock(&lockName), where lockName is the name of a global (extern) 
variable. 



Acqu1reArgumentSp1nLock() 

Equivalent to Acqu1reSp1nLock(p), where p is thcfirst argument of the containing procedure. (This will 

also work if the lock is the first component in a struct *p.) 



ReleaseArgumentSp1nLock() 

Equivalent to ReleaseSplnLock(p), where p is the first argument of the containing procedure. 
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Memory Management 



Blocks within a managed pool of memory can be dynamically allocated and freed within the address space 
of a team using the functions described below. These routines provide essentially the same functionality as 
the standard C library. The memory allocation routines arc provided on a pcr-tcam basis. 

Note that there is one pool of free storage for all processes in the team: when using the standard library 
versions, programmers must be careful to synchronize the processes allocating and freeing this storage. A set 
of memory management routines with internal locking for mutual exclusion is also available (see 
lockedmal loc, below). These routines run more slowly than the standard versions. 



char *ma11oc(s1ze) 
unsigned size; 

Returns a pointer to a memory block that is size bytes long. NULL is returned if there is not enough 
memory available. 



free(ptr) 

char *ptr; 

The memory pointed to is returned to the free storage pool, ptr must point to a block allocated by one of the 
routines listed here. 



char *real1oc(ptr, size) 

char *ptr; unsigned size; 

Changes the size of the block pointed to by ptr to be size bytes. Returns a possibly moved pointer. 



char *ca11oc(e1ements, size) 
unsigned elements, size; 

Equivalent to mal loc(el ements*s1ze), except the area is cleared to zero. Provided for allocating arrays. 



cfree(ptr, elements, size) 

char *ptr; unsigned. elements, size; 

Frees storage allocated by cal 1oc( ). Actually, this function is identical to f ree(ptr ), which may be used 
instead, e 1 erne n ts and s 1 ze arc ignored. 



unsigned Copy(dest1nat1on, source, count) 

char 'destination, 'source; unsigned count; 

A fast block transfer function. Transfers count bytes from source to destination. Returns count. 
Restriction: the source and destination blocks must not overlap. 
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unsigned b1t(dest1nat1on, source, count) 

char 'destination, 'source; unsigned count; 

Identical to Co py(). 

char *Zero(ptr, n) 

char 'ptr; unsigned nj 

Zero memory. Writes n bytes of zeros starting at ptr, and returns ptr. 

c1ear(ptr, n) 

char 'ptr; unsigned n; 

Clear memory. Writes n bytes of zeros starting at ptr. 



swab(pfroro, pto, n) 

char 'pfrom, 'pto; unsigned n; 

Swap the bytes in n 16-bit words starting at the location pfrom into a block starting at the location pto. 

The following functions are of interest only to those managing memory (using the kernel primitives) in 
addition to that provided by the above routines. The current implementation of mal 1oc( ) prevents these 
routines from adding space below the current top of the pool. 



G1veToMalloc(start, length) 
char 'start; 1nt length; 

Add the length bytes of memory at start to the pool used by the allocators described above, returning the 
number of bytes actually installed after alignment and error-checking is done. 



char * GetMoreMallocSpace(m1n, actual) 
1nt rain, 'actual; 

Malloc() calls this function to acquire more space for its pool; a default version is supplied, which is 
replaced if the programmer supplies a routine of this name. GetMoreHallocSpace( ) should return a 
pointer to at least ml n bytes of space and set 'actual to the number of bytes made available; NULL may be 
returned if no more space is to be added to the pool. 

In the default version, free memory is determined and extended based on the memory map and memory 
usage of the team (using the V kernel operations GetTeamS1ze( ) and SetTeamS1ze( )). 

24.1 . Use in multi-process teams 

Hie standard library versions of the allocation and deallocation routines do not enforce exclusion among 
processes within a team; so disastrous things may happen if two or more processes access them 
simultaneously. A multi-process team may use the routines safely by enforcing its own exclusion (e.g., by 
having all allocation/deallocation occur in a single process), or by explicitly linking in a provided version of 
these routines that docs provide locking. 'ITic routines affected arc malloc, rcalloc, free, calloc* cfrcc, and 
Give ToMalloc. (Note, however, that calls to these routines may be hidden in other standard library routines 
as well.) The locking version may be accessed using the compiler flag -1 lockedmal loc; to include it use, 
for example: 

cc68 -V -r other flags yourfile.o -llockedmalloc other libraries 
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This provides full exclusion for all of the routines mentioned, but at a execution-time penalty of up to about 
25%. 
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Naming 



The naming section of the library includes a number of functions that provide a convenient interface to 
V-System naming protocol messages, plus other riaming-relatcd services. Sec chapter 34 for an explanation of 
the naming protocol. 

25.1 , Current Context 

Each process has a current context in which object names that do not begin with the root escape character 
(T) are interpreted, similar to the current working directory of UNIX and other systems. The following 
functions arc provided to query or reset the current context. 



SystemCode ChangeDI rectory (name) 
char *name; 

Change the current context (working directory) for the calling process to be the context specified by name, 
and return a standard system reply code indicating OK if successful, else the reason for failure, name is 
interpreted in the (previous) current context 



1nt chdlr(name) 
char *name; 

This function is identical to ChangeDI rectory (), except that it returns to indicate success or -1 to 
indicate failure. (This interface is provided for UNIX compatibility.) 



char *getwd( pathname) 
char pathname[]; 

Copies the absolute name of the current context (working directory) into the given character array and returns 
its address. (This interface is provided for UNIX compatibility.) 

25.2. Descriptor Manipulation 

V-Systcm servers generally maintain a descriptor for each of the objects they implement. Ivich descriptor 
contains a type field, the associated object's name (relative to a particular context), and additional type 
dependent information such as size, timestamp, owner, etc. The standard header file <Vdircctory.h> defines 
the descriptor types currently known to the system. 

One can read (and in some cases modify) the descriptors of all objects defined in a given naming context by 
opening the associated context directory as a file. A context directory appears as a file of descriptors. A 
context directory can be opened using die standard system Open() routine with the additional bit 
FOIRKCI'ORY specified as a part of the requested file mode. Context directories arc ordinarily opened in 
KB LOCK mode and read using the standard Read( ) routine. 

One caveat is necessary here: an attempt to open a multi-manager context directory in this way will 
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currently fail with the error code MORE.REPUES, since such context directories are modelled as multiple 
files, one per manager. See section 34 for a description of the protocol used to reliably open all partitions of a 
multi-manager context, or the 1 1 stdl r program for a sample implementation. 

One can also read or modify an individual object descriptor using the following functions: 



SystemCode NReadDescp1ptop(name, desc) 
char 'name; 
ArbltraryDescMptor *desc; 

Read an object's descriptor, specifying the object by name. 



SystemCode ReadDescr1ptor(serverp1d, 1nstance1d, desc) 

Processld serverpld; 

Instanceld Instanceld; 

Arb1traryDescr1ptor *desc; ..,, 

Read the descriptor of the object from which the specified instance was created. 



SystemCode NWr1teDescr1ptor(name, desc). 
char *name; 
Arb1traryDescr1ptor *desc; 

Write an object's descriptor, specifying the object by name. 



SystemCode Wr1teDescr1ptor(serverp1d, Instanceld, desc) 
Processld serverpld; .. 
Instanceld Instanceld; 
Arb1trapyDescr1ptop *desc; 

Write the descriptor of die object from which the specified instance was created. 
25.3. Local Names or Aliases 



SystemCode Def1nelocalName( local name, truename) 
chap •localname, •tpuename; 

Defines a local alias "[local namel" for "tpuename", which must be the name of a context.. If truename 
does not begin with a square bracket, it is first mapped in the current context to get an absolute name before 
the alias is defined. The alias is local to the team defining it, and is inherited by teams it creates. 



SystemCode Undef IneLocalName(name) 
char *name; 

Undcfincs a local alias. 



chap *ResolveLocalName(name) v 

char *name; 
Returns the stored absolute name for the given local alias. The returned string should not be modified, and 
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will be freed if the name is later redefined, so beware. 



ClearLocalNames() 

Undefincs all local aliases for this team. It may be useful to call Pr1meCache( ) after calling this routine, to 
reinsert definitions for the system standard aliases. 



SystemCode Def 1neTempArea() 

If the local name [tmp] is not already defined, this function selects an appropriate place to store temporary 
files and defines [tmp] to point to it The function returns OK if successful, else a standard system code 
describing the problem. 

25.4. Naming Protocol Routines 



Processld NameSend(req) 
NameRequest *re(|; 

Sends off the given request message, with the destination determined by the name given in the message. The 
given name must be a null-terminated string; NameSend( ) neither examines nor sets req->name1ength. 
Like Send(), NameSend( ) returns the pid of the rcplicr, and modifies its argument to hold the reply 
message. GetReply ( ) can be used if additional replies arc anticipated. 



SystemCode GetAbso1uteName( namebuf , namelength, context) 
char namebuf[]; 
unsigned namelength; 
ContextPalr 'context; 

Accepts a null-terminated name in namebuf, possibly a relative name or local alias, and modifies it to return 
the absolute name. The size of namebuf is passed in as namelength. If the name specified an existing context, 
its context identifier is returned, as with GctContcxtldO, otherwise contcxt->pid is set to 0. The given name 
need not correspond to any existing object, as long as it is unambiguous what server would implement such an 
object if it did exist, and what its absolute name would be. 



SystemCode GetF11eName( namebuf , namelength, serverp-fd, Instanceld) 
char namebuf []; 
unsigned namelength; 
Processld serverpld; 
Instanceld Instanceld; 

Returns the absolute name for the specified file instance in namebuf. The maximum name length is passed 
in namelength. GetContextName( ) returns OK if the mapping was successful, or a standard system 
error code if a failure occurred. 



SystemCode GetContextId(name, context) 
char *name; 
ContextPalr 'context; 

Interprets the given name in the current context, and returns a corresponding <proccss-id, contcxt-id> pair, 
suitable for caching. The function returns OK if successful, or a standard system error code if an error is 
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detected, such as the given name specifying an object that is not a context . 

Callers should recognize that the ContcxtPair may become invalid at any time, usually due to the server that 
issued it crashing and restarting with a different pid. 

SystemCode GetContextName(namebuf , namelength, context) 

char namebuf[]; 

unsigned namelength; 

ContextPalr context; 
The inverse of GetContextId(). Returns the absolute name for the given context in namebuf. The 
maximum name length is passed in namelength. GetContextName() returns OK if the mapping was 
successful, or a standard system error code if a failure occurred. 

1nt IgnoreRetry(req, p1d, segbuf, segslze, serverpld) 

register MsgStruct *req; 

Processld p1d, serverpld; 

register char *segbuf; 

register unsigned *segs1ze; 
This routine is intended for use only by servers that implement the naming protocol, not for clients that use it 
It determines whether the caller is one of the servers that should ignore the given request req (probably a 
CREATEJNSTANCE_RETRY), returning 1 (true) if so, if not It assumes there is a O-tcrminatcd list of 
pids beginning at req->segPtr in the client's address space, and returns true if the given serverpld is on 
the list If an appended segment was received, segbuf and *segs1ze should indicate its location and size. 
This routine may read in more of the segment: if so, it alters the segslze parameter to reflect what it read. 
The routine assumes segbuf points to an area of at least MAX_APPENDED_SEGMENT bytes. 

25.5. Direct Name Cache Manipulation 

The following routines arc used internally by NameSend() and the local alias manipulation functions. 
They arc not ordinarily called directly in user programs. 

NameCacheEntry •NameCacheAdd(pref 1x, length, from, to, truename, flags) 
char *pref1x, * truename; 
ContextPalr from, to; 
unsigned short length, flags; 

Adds a new entry to the name prefix cache and return a pointer to the new cache record. The cache record 
format is defined in the standard header file <Vnamccachc.h>. If a cache entry already exists for the given 
prefix, it is deleted. Returns NULL if no memory is available to allocate a cache record. 

The prefix argument gives the name prefix to be added, and length is its length (not counting the 
terminating null byte, if any). l"hc prefix is interpreted relative to the from context and must name die to 
context 

The f 1 ags may be any combination of the following bits: 

• DONT.FLUSH 

The cache entry will never be flushed, even if the specified context-pair becomes invalid. 

• ALIAS 

The cache entry specifics a local alias. In tiiis case, prefix is the alias, while truename is the absolute 
name to which the alias maps. 
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• LOGICAL.PID 
The process-id portion of the specified to context is a logical pid. NameSend() will perform a 
6etP1 d( ) with scope ANY.PID each time it attempts to use this cache entry. NOTE: This feature is 
provided for backward compatibility with servers that implement the naming protocol of V version 5 J and 
earlier. It will be removed in a future V release. 



NameCacheEntry *NameCacheLookup(name, context) 
char *name; 
ContextPalr context; 

Checks whether any prefix of the given name matches a cache entry. A pointer to the cache record containing 
the longest matching prefix is returned. If there is no match, NULL is returned. A prefix match is defined as 
all the characters in the prefix matching the corresponding characters in the given name, plus the given name 
containing a delimiter immediately following .the match. 



SystemCode NameCacheDelete(cacheEntpy) 
NameCacheEntry •cacheEntry; 

Deletes the specified name cache entry. NOT_FOUND is returned if cacheEntry does not point to a 
record currently contained in the cache; otherwise OK is returned. 



Pr1meCache() 

Adds a standard set of well-known context names and aliases to the name cache. Normally called only once 
by thefirst team, but also useful after a call to CI ear-Local Names ( ). 

25.6. Environment Variables 

The V-Systcm implements character-string environment variables, much like those in UNIX. In V, a 
process may set variables in its own environment as well as reading environment variables inherited from its 
creator. 

By default, environment variables arc global to a team. The root process of a team begins with an 
environment variable list inherited from its creator (through its team environment block). A newly created 
process initially shares the environment variable list of its creator. A process may separate its environment 
variable list from that of its parent by allocating a new list head of type (EnvironmcntVariablc *), setting 
PcrProccss->cnv to its address, and assigning it a value -typically cither NULL, indicating an empty list, or 
the result of co pyenv( old 11st) (sec below). 



char *getenv(var) 
char *var; 

Returns the value of the given environment variable, or NULL if it is undefined. 'ITic returned string should 
not be modified. 



setenv(var\ value) 
char *vap, 'values 

Sets the given environment variable to the given value, or if value is NULL, sets the variable to be undefined. 
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EnvlronmentVaMable *copyenv(oldlist) 
EnvlronmentVarlable *oldl1st; 

Makes a fresh copy of the environment variable chain beginning with ol dl 1 s t, and returns a pointer to the 
first entry. Useful if a process wants to separate its environment from its parent's. The oldl 1st argument 
should be the value (not the address) of the parent's environment list head. 



dearenv() 

Removes the definitions of all environment variables., 
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26.1 . Numeric Functions 

Most of the functions in the numeric section of the library are not called directly in user programs; they are 
accessed by the C compiler as needed. The following functions are useful in user programs: 



unsigned abs(value) 
1nt value 

Integer absolute value. 



1nt rand() 

Random number generator. Generates pseudo-random numbers in the range from to 2 31 -1. This is. a very 
poor generator, identical to the one provided in Berkeley Unix 4.1. 



srand(seed) 

unsigned seed; 

Resced the rand( ) random number generator. 

26. 2„ Mathematical Functions 

The math-related functions in the V library arc listed below. They are similar to the "section 3M" functions 
of the Unix library. Sec the Unix manual for documentation. 



sin() 


cos() 


tan() 


asin() 


acos() 


atan() 


atan2() 


sinh() 


cosh() 


tanh() 


J0() 


jl() 


jn() 


yoo 


yi() 


- yn() 


hypot() 


cabs() 


gamma() 


fabs() 


foot() 


ceil() 


exp() 


1og() 


1ogl0() 


pow() 


sqpt() 





V Programming 



1 2 March 1986 



27-1 



— 27 — 
Processes and Interprocess Communication 



The V kernel supports processes as abstractions, with operations for process management and interprocess 
communication. Several processes may share an address space on one host Processes sharing an address 
space arc collectively referred to as a team. 

The V kernel also supports the concept of a process group. Any process may create a new group and 
processes may join or leave a group. Most functions that operate on a process also operate on a process group. 
This is achieved by specifying a group identifier in place of the process identifier. Thus, for example, to 
destroy all die processes in the group specified by groupld, the function DestroyProcess(groupld) 
can be invoked. (A single process can be viewed as a special process group: a group with just one member, 
with the process identifier serving as the group identifier.) 

Similarly, messages may be sent to a group of processes, simply by addressing them to a group identifier. 
Typical usages of group communication are notification (e.g. to notify other processes of some event) and 
query (e.g. to locate a specific server). With local area networks providing broadcast and multicast facilities in 
hardware, group communication can be significandy more efficient than using repeated one-to-one 
communication. 

The process and interprocess communication-related functions in the V C library provide services and/or 
interfaces between processes and the V kernel. They have no direct analog in the standard Unix C library. 
These functions provide a convenient interface to kernel-provided services. Some of the functions execute 
kernel trap instructions, while others send messages to the kernel-server inside the kernel. 

A kernel operation executes as a single indivisible function call as far as the C programmer is concerned. 
Each kernel operation takes zero or more arguments and returns a single value. 

In the descriptions below, the active process or invoking process always refers to the process that executed 
the kernel operation. 

Some operations such as SctTcam Priority and SctTimc arc intended to be used only by "operating system" 
or management processes and should not be used by application programs. 

This chapter is divided into four sections: 1) process-related kernel operations, 2) other process-related 
functions, 3) process group related kernel functions and 4) interprocess communication-related functions. 

27.1. Process-Related Kernel Operations 



SystemCode ClearModlfedPages(pid) 
Processld p1d; 

Clears the dirty bits for all pages in the address space in which the process specified by pi d resides. 



Processld CreateProcess(pr1or1ty, 1n1t1alpc, 1n1t1a1sp). 
short priority; char *1n1t1a1pc, *1n1t1alsp; 

Create a new process with the specified priority, initial program counter and initial stack pointer and return its 
unique process identifier. 
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The priority must be between and 255 inclusive, with the highest priority. (Sec the discussion on 
priorities with the description of QueryProcessPMor1ty().) 1n1t1alpc is the address of the first 
instruction of the process to be executed outside of the kernel. Generally, Initial sp specifics the 
initialization of the stack and general registers and is processor-specific. In the case of the Motorola 68000, 
1n1t1alspisa simple long word value that is assigned to the user stack pointer. 

The process is created awaiting reply from the invoking process and in the same team space. The segment 
access is set up to provide read and write access to the entire team space of the newly created process. The 
creator must reply to the newly created process before it can execute. If there arc no resources to create the 
process or the priority is illegal, a pid of is returned. 

Usually programmers will # prefer the Create ( ) call described later in this chapter. 



Processld CreateTeam(pr1or1ty, 1n1t1alpc, 1n1t1a1sp, Ihost) 

short priority; char *1n1t1alpc, *1n1t1a1sp; Processld Ihost 

Create a new team with initial or root process having the specified priority, initial program counter, and initial 
stack pointer. 1 host specifics which (existing) logical host the new team should be placed into. A value of 
specifics the logical host of the invoker. 

CreateTeam( ) is similar to CreateProcess( ) except the new process is created on a new team. The 
new team initially has a null team space. It is intended that the creator of the team will initialize the team 
address space and root process state using SetTeamS1ze(). MoveTo(), and Wr1teProcessState(). 
pr 1 or 1 ty must be a value between and 255. 

CrcatcTeam returns if there arc no resources to create the team or the root process, or the priority is 
illegal. 

Warning: CreateTeam( ) will be restricted to the first team in the near future. 



Processld Creator(pld) 
Processld p1d; 

Return the process id of the process that created p1d. If p1d is zero, return the creator of the invoking 
process. I f p 1 d docs not exist or is the root process of the initial team, return 0. 



SystemCode DestroyProcess(pld) 
Processld p1d; 

Destroy the specified process and all processes that it created. When a process is destroyed, it stops executing, 
its pid becomes invalid, and all processes blocked on it become unblocked (eventually). 
1, DestroyProcess( ) may also be used to destroy a process group by specifying a group identifier with 
p1d. DestroyProcess() returns OK if p1d if successful, else a reply code indicating the reason for 
failure. DestroyProcess(O) is suicide. If p1d specifics a process group, then all processes in that group 
(and llicir descendants) arc destroyed. 

Usually programmers will prefer the Oes troy( ) call described later in this chapter. 



Processld GetObjectOwner(objectPid) 
Processld objectPId; 

Return the process-id of the owner of the specifed object Currently the only type of object supported is a 



Processes blocked on a nonexistent processes arc detected and unblocked by the clock interrupt routine checking periodically. 
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team. Thus ob JoctPI d must specify a process on the team whose owner is desired. 

Processld GetP1d( "logical 1d, scope) 
1nt loglcalld, scope; 

Return the pid of the process registered using SetP1d( ) with the specified logical id and scope, or if 
not set 

The scope is one ofi 

LOCAL_PID Return a locally registered process only. 

ANY_PID Return a local or remote process. 

If logical 1d is ACTIVE.PROCESS, the pid of the invoking process is returned. If the scope is any, the 
kernel first looks for a locally registered process; if one is not found, the kernel broadcasts a request for a 
process identifier registered as this logical id to other workstations running the V kernel on the network. In 
this way, a kernel can discover the process identifiers of the standard server processes from other kernels, or at 
least from the kernel that is running the server process of interest 

Note: GetP1d( ) and Se1:P1d arc being phased out New programs should use the group communication 
facility instead. The REMOTE_PlD scope available in previous releases is no longer supported. 

Processld GetTeamRoot(pld) 
Processld p1d; 

Return the process identifier of the root process of the team containing p1d, or zero if p1d is not a valid 
process identifier. A p 1 d of zero specifies the invoking process. 

char *GetTeamS1ze(p1d) 
Processld p1d; 

Return the first unused location in the team space associated with p1d. asset by SetTeamS1ze( ). I f p 1 d is 
zero, the size of the invoking process's team is returned. If p1 d docs not exist is returned. 



QueryKerne1(p1d, groupSelect, reply) 

Processld p1d; 1nt groupSelect; Message reply; 

Query the kernel on the host where process p1d is resident A p1d of zero specifics the invoking process's 
kernel. 

The groupSelect field specifics what information is to be returned in the reply message. The available 
group selection codes arc MACHINK_CONFIG, to return information about the processor configuration, 
PIIRIPHERAL.CONKIG, to return a list of peripherals available on the machine, KKRNL-LJTONRG, to 
return die kernel's configuration parameters, MKMORY_STATS, to return memory usage statistics, and 
KKRNHLJ5TATS, to return other kernel statistics. 'Ilicsc codes, and the corresponding structures that may 
be returned, arc defined in the standard header file <Vqucrykcrncl.h>. 



SystemCode QueryProcessorUsage(p1d, usage, tusage) 
Processld p1d; unsigned "usage, *tusage; 

Return the time allocated so far by die processor to process p1d in *usage and return total for the entire 
team in *tusage if tusage is non-zero. Time is returned in "clicks". If pid is zero, the time for the 
invoking process is returned. If p1d is equal to the logical host name (LHN) shifted left by 16 bits, the time 
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allocated to the idle process is returned. 
The function itself returns a rcplycodc indicating success or otherwise. 

unsigned short QueryProcessPr1or1ty(p1d) 

Processld p1d;' 
Returns the composite priority of the process with p1d. A p1d of zero specifies the invoking process. If p1d 
docs not exist, is returned. 

The 16 bit composite priority field of a process effectively consists of two concatenated 8 bit fields. The 
higher-order field contains the team priority; the lower-order field the process priority within the team. 
These are initialized when the processes arc created (sec CreateProcess() and CreateTeam()) and 
may be manipulated with SetProcessPr1or1 ty( ) and SetTeamPr 1or1ty( ). The ready process with 
the lowest number in its composite priority field runs. 

Processld QueryProcessState(p1d, pb) 
Processld p1d; ProcessBlock. *pb; 
Copy the state of the process into the structure pointed to by pb. The various fields in the structure are 
defined in <Vproccss.h>. Their meanings should be self-explanatory. 

The message buffer is only available if p1d is the invoking process or is awaiting reply from the invoking 
process. If not, the appropriate fields in the structure are zeroed. 

If p1 d is zero, the process state of the invoking process is returned. If p1 d docs not exist, is returned; 
otherwise, p 1 d is returned. 

Processld ReadProcessState(p1d, state) 

Processld p1d; Processor.state *state; 

Copy the machine-specific processor state into the structure pointed to by state. The information returned 
is a subset of that returned by QueryProcessState( ). 

If p1 d is zero, die processor state of the invoking process is returned. If p1 d docs not exist, is returned; 
otherwise, p 1 d is returned. 

SystemCode ReturnModlf 1edPages(p1d, buffer, bufferlen) 

Processld p1d; unsigned buffer[256]; unsigned *bufferlen 

Clears the modified bit of each page table entry for the team specified by p1d. Returns the starting address of 
each page of memory in the team whose modified bit was on before being cleared. ITic size of the buffer may 
not be sufficient to contain the starting address of all dirty pages in the team's address space, although it 
should be sufficient for most. The operation docs not clear the modified bit of any page whose starting 
address it cannot place in die invokcr's bulTcr. Thus, the invokcr need simply rcinvokc 
ReturnModlf ledPages to continue with the the operation if the return code indicates that more dirty 
pages might be outstanding. This is indicated with a return code of RETRY instead of OK. The last valid 
page address returned is delimited by a NULL word in the case where the buffer is not completely filled. 
bufferlen returns the number of modified page addresses returned in buffer. 

1nt SameTeam(p1dl, p1d2) 
Processld pldl, p1d2; 

Return true (non/.cro) if the processes specified both exist and arc on the same team; otherwise return false. 
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If either pid is zero, the invoking process is assumed. 



SetObjectOwnor( objectPId, newOwner) 
Processld objectPId, newOwner; 

Set the kernel-maintained owner of the object specified by objectPId. Currently the only type of object 
supported is a team. Thus objectPId must be the pid of a process on a particular team. Ownership of a 
team implies that unrestricted access to the team's address space using MoveTo and MoveFroro operations 
without having a process in die team first send a message to the owner. 



SetP1d(1og1ca11d, p1d, scope) 

1nt loglcalld, scope; Processld p1d); 

Associate p1d with the specified logical id within the specified scope. Subsequent calls to GetP1d() with 
this logical id and scope return this pid. This provides an efficient, low-level naming service. 

The scope is one oft 

LOCAL_PID Register the process locally. 

ANY_PID Register the process globally. 

The local scope is intended for servers serving only the local workstation. The any scope permits both local 
and remote access. 

Note: GetP1 d( ) and SetP1 d arc being phased out New programs should use the group communication 
facility instead. The REM0TE_F1D scope available in previous releases is no longer supported. 



SystemCode SetProcessPr1or1ty(p1d, priority, decay) 

Processld p1d; unsigned short priority, unsigned decay; 

Set the priority of process p1d to priority. If p1d is zero the priority of the invoking process is set to 
priority, priority may beany integer between and 255. (Sec QueryProcessPr1or1ty() fora 
discussion of process priorities.) If decay is nonzero, the priority is incremented every decay "clicks" until 
it reaches 255. 



SystemCode SetTeamPr1or1ty(p1d, priority) 
Processld p1d; unsigned short priority; 

Set the team priority of the team associated with p1d to priority. If p1d is zero the priority of the 
invoking process's team is set to priority, priority must be an integer between and 255. (Sec 
Query Process Pr 1or 1 ty( ) for a discussion of team priorities.) Teams with pr 1or 1 ty 254 or 255 do not 
run. 

SetTeamPr1or1ty( ) changes the absolute scheduling priority of each process on the team by modifying 
the team priority field of the composite priority for each process. This operation is intended for 
implementing macro-level scheduling and is restricted in use to the first team. Other teams should use 
ChangeTeamPr1or1ty( ) to request special scheduling service. 



char *SetTeamS1ze(p1d, addr) 
Processld p1d; char *addr; 

Sets the first unused address for the team containing p1d to addr. 'ITic new team size may be either greater 
or smaller than die previous size. The new team size is returned; diis will normally.be equal to addr. If there 
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was not enough memory available to grant the request, the return value will be less than addr; if addr was 
below the starting address for team spaces on the host machine, the team space will be set to null and its 
starting address will be returned. Thus Se tTe amS 1 ze ( p 1 d , ) is a machine-independent way of setting a 
team space to null. 

A pid of specifics the invoking process. Only the creator of the team or members of the team may change 
the team size and (consequently) the specified process must be local. 



1nt Va11dP1d(p1d) 
Processld p1d; 

Return true (nonzero) if p1 d is a valid process or group identifier; otherwise return false. 



Processld Wr1teProcess$tate(p1d, state) 
Processld p1d; Processor_state *state; 

Copy the specified process state record into the kernel state of the process specified by p1d and return p1d. 

The specified process must be the invoking process, or awaiting reply from the invoking process. 
Wr1teProcessState( ) returns if the process docs not exist, is not awaiting reply or there is a problem 
with the state record. The kernel checks that the new state cannot compromise the integrity or security of the 
kernel. 

A p1d of specifics the invoking process. A process that writes its own processor state affects only the 
machine-independent per-process area information kept as part of the state record (see section 18.4.3). 

27.2. Logical Host-Related Functions 



Processld CreateHost(pr1or1ty, 1n1t1a1pc, 1n1t1a1sp) 

short priority; char •InUlalpc, *1n1t1alsp; Processld Ihost; 

Create a new team in a separate logical host with initial or root process having the specified priority, initial 
program counter, and initial stack pointer. This routine is the same as CreateTeam except that a new logical 
host is created for the new team. 



SystemCode DestroyHost(pld) 
Processld p1d; 

l3cstroy the logical host in which the process specified by p1d resides. When a process that is frozen is 
destroyed, any queue local IPC operations on it will be rc-cxccutcd rather than returned with a failure status 
code. Also, queued reply messages will be forwarded rather than simply destroyed. 



SystemCode ExtractHost(p1d t optype, buffer, length) 

Processld p1d; 1nt optype; char *buffer; unsigned *1ength; 

Extract the kernel descriptor information for the logical host in which the process p1d resides and place it in 
the buffer pointed to by buffer, length specifics the size of buffer provided on invocation and returns the 
size of the descriptor information returned. This operation can only be invoked on local logical hosts, 
optype is cither the manifest constant QUERYHOSTCASE or EXTRACTHOSTCASE (specified in 
Vnrigrate.h). Ilic former indicates that only summary information should be returned on the number of 
processes, teams and memory used by the logical host. The is returned in a HostResourcesRec structure, 
as defined in Vm1 grate. h. Hie latter optype indicates that the full kernel descriptor information for the 
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logical host should be returned. The full descriptor information returned is not intended to be interpreted 
outside the kernel and should only be used by the Transf erHost operation to be reinstalled into another 
machine's kernel. 



SystemCode FreezeHost(pld) 
Processld p1d; 

Freeze the logical host in which p1d resides so that its address spaces and the kernel state associated with its 
teams and processes arc not modified. This will cause all kernel operations on the logical host to be deferred 
and the priority of the teams in the logical host to be set to non-runnable. 



SystemCode TransferHost(p1d, buffer, length) 

Procossld p1d; char *buffer; unsigned length 

Takes the kernel descriptor information generated by ExtractHost and installs it into an existing logical 
host that must have an equivalent number of teams already in it. Furthermore, the teams must have only a 
root process in them. The existing logical host is renamed by this operation to be the logical host specified in 
the descriptor information, as arc all the teams in it The result is a logical host that is equivalent to the one 
described in the descriptor information and the effective deletion of the "blank" logical host that was used as 
an installation base. The owner of the "new" logical host is the invokcr of the operation. 

SystemCode UnfreezeHost(pld) 
Processld p1d; 

Unfreeze the logical host in which p1d resides. All deferred kernel server and IPC operations are executed 
and the priority of the teams in the logical host arc set to their previous runnablc values. 

27.3. Other Process-Related Functions 



Processld Create(pr1or1ty, function, stackslze) 

short priority; char 'function; unsigned stackslze 

Create a new process executing the specified function with the specified priority and stack size. The new 
process is blocked, waiting for a reply from the creator. The function Ready ( ) should be used to start the 
process running. The new process is on the same team as its creator, and inherits the creator's standard input, 
output, and error files, and the creator's current context (current working directory). 

Create returns the pid of the new process, or zero if a process could not be created. This function is 
usually preferable to calling the kernel operation Cre@teProcess( ) directly. 

Processld Ready(p1d, nargs, al an) 

Processld p1d; unsigned nargs; Unspec al an; 

Set up the stack of the specified process and reply to it, thus placing it on the ready queue. The values al, 
.... an appear as arguments to the root function of the new process, while nargs is die number of 
arguments passed. Zero is returned if there is a problem, else p1d is returned. 

Destroy(pld) 

Processld p1d; 
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Destroy the specified process. If the destroyed process was on the same team as the invoking process, the 
memory allocated to its stack by Create ( ) is freed. Warning: Do not invoke Destroy( ) on a process that 
wasnotcrcatcdbyCreate();useDestroyProcess() in that case. 



Su1dde() 

Destroy the invoking process and free its stack. Su1c1de() is identical to Destroy(O), and the same 
warning applies. 

exit (status) 

1nt status; 
Terminate the execution of the team (i.c program), after closing all open files. The status is sent to the 
creator of the team requesting termination. Thus, using the V executive, control is returned to the command 
interpreter. In bare kernel mode, control is returned to the PROM monitor. 



abort () 

Abort execution of the team by causing an exception in the calling process. This routine can also be called 
with parameters. If it is, the standard exception handler will interpret the first parameter as a pointer to a 
prlntf -style format string. The other parameters will be interpreted as values to be printed using that 
string. In an effort to keep the standard exception handler simple and robust, the number of Xs's in the 
format string must not exceed 8, nor may any of the strings (cither the format string or strings to be printed) 
exceed 128 characters in length. 

The format specifier Xz is included in addition to the usual specifiers. %z will interpret its argument as a 
SystemCode, and print the result of running Error-String with that code as its parameter. 

ChangeTeamPr1or1ty(p1d t priority) 
Processld p1d; short priority; 

Set the priority of the team in which process p1d resides to priority. If p1d is then the invoking process 
is implied, priority must be one of the manifest constants: REAL-TIME1 through REAL-TIME4 (of 
which REAL-TIME1 is the most privileged priority), FOREGROUND, BACKGROUND, GUEST, and 
STOP-TEAM -PRIORITY. Hie first team runs at priority REAL-TIME3, locally invoked foreground 
programs run at FOREGROUND, locally invoked concurrent (&) programs run at BACKGROUND, and 
remotely invoked programs run at GUEST priority. STOP-TEAM - PRIORITY makes the processes of a 
team nonrunnablc. FOREGROUND, BACKGROUND, and GUEST programs arc time-sliced in a round- 
robin scheme, with lower priority teams only getting the . time slice if no higher priority teams exist 
Management of team priorities is done by the team server, which uses the privileged SetTeamPMorlty 
kernel operation to actually change team priorities. 

27.4. Process Group Operations 



Groupld CreateGroup(1n1t1a1_»ember, type) 

Processld 1n1t1al_member; unsigned type; 
Create a new group of the specified type (UNRFSTRlCTEDJjROUPJW1lX)CAL..GROUP_BlT) and 
make 1n1t1a1_meraber the first member. 'Hie invoking process is made the first member of the process 
group if 1n1t1a1_member is 0. If the UNRIiSTRICTED_GROUI , _MT is set in type, then any process 
may join the groupTothcrwisc only processes of the same user may join. One can specify that only processes 
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on the same host as 1n1t1a1_member may join the group with the LOCAL_GROUP_BIT bit in type, 
thus allowing certain optimizations. 1n1t1al_memteer may also specify a process group, in which case 
every member of 1n1 tia1_mernber becomes a member of the newly created group. 

Returns the group id of the newly created group if successful, otherwise. 



SystamCode Jo1nGroup(groupId, p1d) 
Groupld groupld; Processld p1d; 

Add the process or process group specified by p1d to the process group groupld. Group groupld must 
exist. Well known groups are defined in the include file <VgroupidsJi>. If p1d is 0, the invoking process is 
added to the group. If p 1 d specifies a process group, every process of that group joins the group specified by 
group 1 d. Returns OK if successful, else a reply code indicating the reason for failure. 



SystamCode LeaveGroup(groupId, p1d) 
Groupld groupld; Processld p1d; 

p1d leaves the process group with group id groupld. If p1d is 0, the invoking process leaves the group. 
Again, p 1 d may cither specify a process or a process group. 



SystemCode QueryGroup( groupld, p1d) 
Groupld groupld; Processld p1d; 

Query the kernel to sec if p1d (the invoking process if p1d is 0) would be allowed to join the group with the 
specified groupld. Returns OK if so, otherwise NO„PERMISSION if not allowed, DUPLICATED AME 
if already in, and NOT_FOUND if group does not exist (not at least one member located). 

27.5. Interprocess Communication 



1nt Awa1t1ngRep1y(fromp1d, awaitlngpid) 
Processld frompid, wa1t1ngp1d; 

Return true (nonzero) if awaitlngpid is awaiting reply from frompid; otherwise return false. 



SystemCode ForceExcept1on(p1d) 
Processld p1d; 

Causes process p1d to send an exception message to the exception server. The exception type is 
FORCEKXCEPTiON. 



SystemCode ForceSend(msg, fromPId, toP1d) 
Message msg; Processld fromPId, toP1d; 

Force process fromPId to send msg to process toP1d. ForceSendcannot be reinvoked on a process until 
the first invocation is terminated by replying to the process. I.e. there can only be at most a single 
ForceSend in effect for any given process. 



Processld Forward(msg, frompid, topld) 

Message msg; Processld frompid, topld; 
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Forward the message pointed to by msg to the process specified by top Id as though it had been sent by the 
process frompld. 

The process specified by frompld must be awaiting reply from the invoking process. The effect of this 
operation is the same as if f romp id had sent directly to topld, except that the invoking process is noted as 
the forwarder of the message. Note that Fop ward ( ) does not block. 

Forward() returns topld if it was successful, if unsuccessful. If topld is invalid, frompld is 
unblocked with an indication that its Send ( ) failed. (Namely, the Send ( ) returns zero, and the rcplycode 
field of the reply message is set to BAD_FOR W ARD.) 



Processld Forwarder(pld) 
Processld pldj 

Return the process id that forwarded the last message received from p1d, providing p1d is still awaiting reply 
from the invoking process. If the message was not forwarded, p1d is returned. If p1d docs not exist or is not 
awaiting reply from the invoking process, is returned. If the last message received was sent to a process 
group, Forwarder ( ) returns the group identifier the message was sent to. 



Processld GetRep1y(msg, timeout) 
Message msg; 1nt timeout; 

Returns the next reply message from a group Send() in msg and returns the process identifier of the 
replying process. If no messages are available within the timeout period, GetRep1y( ) returns 0. A typical 
message transaction thus consists of a Send() (which returns the first reply) followed by any number of 
GetRep1y( ). However, all replies for a message transaction arc discarded when the process sends again, 
initiating a new message transaction. (Note: Many library routines, such as prlntf ( ) arc implemented with 
message passing primitives, thus ending the last message transaction when they are called.) The timeout is 
given in clicks. 



SystemCode MoveFrom(srcp1d, dest, sre, count) 

Processld srcpld; char *dest, *src; unsigned count; 

Copy count bytes from the memory segment starting at sre in the team space of srcpld to the segment 
starting at dest in the invoking process's space, and return the standard system reply code OK. 

Unless the invokcr is die owner of the team in which srcpld resides, the srcpld process must be 
awaiting reply from the invoking process and must have provided read access to the segment of memory in its 
space using the message format conventions described for Send( ). MoveFrom( ) returns a standard system 
reply code indicating the reason for failure if any of these conditions arc violated. 



SystemCode MoveTo(destp1d, dest, sre, count) 

Processld destpld; char *dest, *src; unsigned count; 

Copy count bytes from the segment starting at sre in the invoking process's team space to the segment 
starting at dest in the team space of the destpld process, and return the standard system reply code OK. 

Unless the invokcr is the owner of the team in which srcpld resides, the destpld process must be 
awaiting reply from the invoking process and must have provided write access to the segment of memory in 
its space using the message format conventions described under Send(). MoveTo() returns a standard 
system reply code indicating the reason for failure if any of these conditions arc violated. 



Processld Recelve(msg) 
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Message msg; 

Suspend the invoking process until a message is available from a sending process, returning the pid of this 
process, and placing the message in the array pointed to by msg. To determine if the message was sent to a 
process group sec Forwarder (). 

Processld Rece1veW1tfiSegment(msg. segbuf, segslze) 
Message msg; char *segbuf; unsigned *segs1ze; 

Suspend the invoking process until a message is available from a sending process, returning the pid of this 
process, and placing the message in the array pointed to by msg and at most the first * segslze bytes of the 
segment included with the message in the buffer starting at segbuf. The actual number of bytes in the 
portion of the segment received is returned in • segslze. (Note: This may be zero even if a segment is 
specified in the message.) Additional parts of the segment specified in the message may be transferred with 
MoveFrom(). 

Processld Rece1veSpec1f1c(msg, p1d) 
Message msg; Processld p1d; 

Suspend the invoking process until a message is available from the process p1d or from a process in the 
process group specified by p1d, returning the pid of this process, and placing the message in the array 
pointed to by msg. 
If p 1 d is not a valid process or group identifier, Rece 1 veSpec 1 f 1 c ( ) returns 0. 

Processld Reply(msg, pid) 

Message msg; Processld p1d; 

Send the specified reply message to the process specified by p1d and return p1d. 

The specified process must be awaiting reply from the invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. Note: Messages that have been received but not replied to consume 
kernel resources until the receiver exits. ITicrcforc, each process should invoke Reply ( ) on every message it 
receives. If no reply is required, then Reply ( ) should be invoked with a message whose replycodc is set to 
DISCARD REPLY. Such a reply message is not delivered to the sender, but releases kernel resources and 
allows die sender to (eventually) unblock (with a KKRNKLJNMKOUT error reply code if no replies were 
received at all). 

ReplyW1thSegment(msg, p1d, sre, dest, bytes) 

Message msg; Processld p1d; char *src, *dest; unsigned bytes; 

Send the specified reply message and segment to the process specified by p1 d and return p1 d. 

Hie specified process must be awaiting reply from the invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. The segment size is currently limited to 1024 bytes. A 
ReplyW1thSegment() with a nonzero segment size may only be used to reply to an idempotent request 
(sccSend()). 

Processld Send(msg, p1d) 

Message msg; Processld p1d; 

If pid specifics a single process group, send the message in msg to the specified process, blocking the invoking 
process until the message is both received and replied to. The array specified by msg is assumed to be 8 long 
words. The reply message overwrites the original message in the array. 
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If Send ( ) completes successfully, it returns the pid of the process that replied to the message. The pid 
returned will differ from that specified in the call if the message is forwarded by the receiver to another 
process that in turn replies to it. If the send fails (for instance, because the intended receiver does not exist), 
Send( ) returns the pid of the process the message was last forwarded to (the pid it was sent to, if it was never 
forwarded). The kernel indicates the reason for the failure by overwriting the first 16 bits of the message with 
a standard system reply code. (This places it in the replycode field for reply messages that follow the standard 
system format) 

If p1 d is a process group identifier, the message is sent to all processes in the group on a best effort basis and 
Send( ) blocks until a first process replies. The first reply message overwrites the original message. Further 
replies of the current message transaction may be received with GetReply( ). Send initiates a new message 
transaction, effectively flushing all messages of the last transaction. 

All messages must follow the kernel message format conventions as follows. The first 16 bits of the message 
are considered to be a request code or reply code. Some of -high-order 8 bits within request and reply codes 
are assigned special meanings, and currently-unused bits within this subficld are reserved for future use. The 
bit names given below are defined in the standard header file < Venviron Ji>. 

REPLY.BIT is reset if a request message is being sent; set if a reply message. 

SYSTEM_CODE is set if the request code or reply code is considered a standard system code. Applications 
can use special request codes and reply codes internal to their programs but use standard 
ones for interfacing to other programs and the system. 

Several other bits are interpreted with the following special meanings if the message is a request 

READ_BIT is set if read access is provided to a memory segment If this bit is set the kernel interprets 

the last 2 words of the message as specifying a pointer to the start of the segment and the 
size in bytes of the segment respectively. The kernel then makes the segment available to 
the receiving process using MoveTo and Move Front 

WRITEJHT is set if write access is provided to a memory segment The segment is specified as 
described above. Both read and write access can be provided by setting both bits 4 and 5. 

DATAGRAM.SENDJBIT 

Experimentally, the V kernel currently supports the concept of real-time communication. 
In this mode, messages arc communicated to a single process or a group of processes on a 
best effort basis. A process will only receive the message if it is rcccivc-blockcd waiting for 
it 'ITic send operation docs not block. Thus, one cannot reply to a real-time send. 'ITiis type 
of communication is intended for situations, where, for example, a process continuously, in 
regular intervals, sends update information to a group. ITiis mode of communication is 
specified by setting the DA TAG R A MJ5BN D_BIT of the rcqucstcodc of the message. 

It is intended and assumed that most requests can be assigned a request code that is stored in the first 16 bits 
of the request message,' so that the bits arc set correctly for the request by the value of the request code. 

The following bits have special meaning in reply codes: 

ANONYMOUS.RKPLY.BIT 

Reply as the forwarder of the message. 'ITiis feature allows processes to join groups and 
reply to messages anonymously. 

REPLY_SEGMENT_BiT 

Reply segment has been specified; If this bit is set in a call to ReplyWI thSeg( ), the 
kernel interprets the last 2 words of the message as specifying a pointer to the start of the 
reply segment and the size in bytes of the segment respectively. 

IMMEDIATE.REPLY.BIT 

Don't delay this reply, even if it is to a group send. If tliis bit is not set replies to group 
sends arc delayed slightly within the replying kernel to avoid swamping the sending kernel 
with back-to-back packets. 
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This chapter describes a number of routines related to program execution. Included arc routines for 
program loading and. execution, selecting hosts for remote execution of programs, execution of Unix 
commands remotely on a Unix V server (see section 43), routines that provide compatibility with various 
Unix program execution routines, and other routines. 

28.1 . Program Execution 

Ppocessld LoadProgram(argv, hostSpec, rtMsg, path, concurrent, error) 
char *argv[]; /• Program arguments (Including name). */ 
SelectionRec *hostSpec; 

/• Specifies the host to execute on. 
(NULL ■> default. I.e. local host) •/ 
RootMessage *rtMsg; 

/• Root message to use. NULL -> default settings •/ 
char *path; /• Search path to use fop finding the ppogpam 

,n file. NULL Indicates that the default should 

" <: he used. */ 

1nt concuppent; /* Specifies whether the ppogpam should be 

owned by the system (concurrent * 1) op 
by the user (concurrent ■ 0). •/ 
SystemCode *eppop; /• Retupn code. •/ 

LoadPpogram() interacts with die team server on the specified host, to create a new team and load a 
program image into the new team space. The program is placed in a separate team and is set ready to run. 

The array apgv contains pointers to the character string arguments to be passed to the new team. By 
convention. apgv[0] should point to the name of the program. The last clement of the array must be a null 
pointer. 

The hostSpec argument is used to select a host to execute the new program. If hostSpec is NULL, the 
program is run locally. Alternatively, hostSpec can be a pointer to a select-ion record, as defined by the 
Sel ectlonRec structure in Vteams . h. In this case, if die ti-amsf.rvi-rpid field of the selection record is 
non-zero, then this value is assumed to be a pid of a team server on the desired host. If, however, die 
teamSePvepPId field is zero, Uicn an 'arbitrary' remote host is selected, according to the constraints 
specified in the other fields of the record. NOW!: This method of host selection is likely to change in future 
releases of the system. 

The rtMsg argument holds the root message to be passed to the new team. This message specifics file 
instances to be used for standard input, output, and error, the team environment block, and some other 
information. The fields in the message arc described in detail in section 18.4.1. If ptMsg is given as NULL, 
then a 'default' root message is used (sec the description of the Def aul tRootMessage( ) routine, below). 

The concuppent argument specifics whether the team is to be "owned" by the process executing the 
LoadPpogram( ) call (if concurrent is zero) or by the team server itself (if it is nonzero). The team server 
destroys any team whose owner ceases to exist; thus, programs to be run "in the background" should be 
flagged as concurrent. 
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path specifics the search path that is used to locate the code file for the program that is to be executed. A 
search path is a character string consisting of a sequence of name prefixes separated by spaces. If path is 
NULL, then the value of the "PATH", environment variable is used instead, or, if the "PATH" environment 
variable is not set, the 'default' searchpath. This default search path is " ./ [bin]", which indicates that 
the program code file is searched for first in the invokcr's current context, and then in the [bin] context. 
(Note that the search path mechanism also involves checking for machine-specific program name suffixes, as 
described in section 3.7.) 

If the named program is not found, then the f execute program is invoked instead, to attempt to execute 
the program remotely on the server that is providing the invokcr's current context See section 3.4 for further 
details. 

Note: If argv[0] is an absolute name (that is, beginning with • [ '), then a search path is not used, nor is 
the /execute program used in the case of a failed match. 

LoadProgram( ) returns the pid of the new team's root process, or to indicate an error. A standard 
system code is return in the location pointed to by error. The new team can be started running by replying 
to the pid returned, using the same root message as was passed to LoadProg. 

Processld ExecProgram(argv, hostSpec, rtMsg, path, status, error) 
char *argv[]; /• Program arguments (Including name). •/ 

SelectlonRec *hostSpec; 

/• Specifies the host to execute on. 

(NULL -> default. I.e. local host) */ 
RootMessage *rtMsg; /* Root message to use. NULL -> default settings */ 
char *path; /* Search path to use for finding the program 

file. •/ 
1nt 'status; /* Return code from program executed or NULL 

1f the program 1s to be run concurrently. */ 
SystemCode *error; /* Return code. */ 

ExecProgram( ) is like LoadProgram( ), except that it also starts the new team running (by replying to 
it). The arguments argv, hostSpec, rtMsg, path, and error arc the same as for LoadProgram( ). 

If the status parameter is NULL then the program is run concurrently, otherwise the function waits until 
the program has terminated and returns its exit status in status. 



Wa1t(p1d, status) 
Processld p1d; 
1nt 'status; 

Wait for the team whose root pid is specified by p1d to expire, and then return its exit status code in the 
location pointed to by status. 



DefaultRootMessage( rtMsg) 

register RootMessage *rtMsg; 

This routine sets up the structure pointed to by rtMsg to be the 'default' RootMessage for any program 
that the invokcr should load. In particular, the stdl n, stdout and stdl n servers and instance ids arc set to 
be those of the invokcr. 
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28.2. Host Selection 



1nt QueryHosts(spec, descArray, numHosts, error) 
SelectlonRec *spec; /* Host selection spec. V 
SelectionRec *descArray; 

/* Array for returning descriptors of selected 
hosts. •/ 
1nt numHosts; /* Maximum number of selections to return. 

Also the size of pidArray. */ 
SystemCode *error; /* Status code. */ 

Select a set of hosts for remote execution of programs. Nothing is actually executed - this routine merely 
returns candidate hosts for remote execution. QueryHosts( ) returns descriptor records for hosts selected 
in descArray which meet the selection criteria specified by spec. At most numHosts selections arc 
returned. The number of hosts actually selected is returned as the function value, error returns a system 
status code for the operation. 

If spec is NULL then the default specification is used (see the description of 
DefaultSelect1onRec(), below). 

The format of a selection record is specified in Vteams . h. The p1d field of a SelectlonRec specifies 
the team server of a candidate host It is this process-id that should be used with any subsequent calls to 
ExecProgram( ) or LoadProgram( ). 

QueryHosts() finds candidate hosts by sending a message to the process group containing all team 
servers in die system (the VTEAM_SERVER_GROUP). Only those hosts which satisfy die requirements 
specified in spec will reply to this message. 



DefaultSelectlonRec(hostSpec) 

SelectlonRec *hostSpec; /* assumed to be non-NULL. •/ 

Sets up the SelectlonRec structure pointed to by hostSpec, so that it can be used (as an argument to 
QueryHosts(), ExecProgram() or LoadProgram()) to select an 'arbitrary' remote host. This 
currently specifics the following minimum resource requirements: 

• 1 free team descriptor. 

• 10 free process descriptors. 

• 200 Kbytes of free memory. 

• I,css dian 50% processor utilization; 

• No one logged into the host 

28.3. Remote Execution of Unix Commands 



SystemCode RemoteExecute(processF1le, programname, argv, mode) 
File *processF1le[2]; char •programname; 
char *argv[]; unsigned short mode; 

Cause the specified program to be executed on the server that provides the invoking process's current context, 
by opening a file in FEXKCUTK mode. Of course, this server must be a Unix V server (see section 43). This 
function is used by die f execute program. 

The argv parameter is an array of null-terminated strings which arc to passed as arguments to the program. 
The array itself is terminated by a null pointer, mode should be 1 READ or I'CRKATK. A l ; ilc structure 
describing a stream from which die program's standard output can be read is returned in processFI le[0]. 
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If the mode is FCREATE, a File structure describing a writeable stream that is fed into the program's 
standard input is returned in processF1le[l]. RemoteExecute() returns OK if successful, else a 
standard system code describing the error condition. 

Closing the writeable file passes an end-of-file indication on to the remote program. Closing the readable 
file terminates the program. 

28.4. Other Program Execution Routines 



Processld Exec1(1nput, output, errput, status, error, argO) 

char *argO; 

F11s *1nput, 'output, •errput; 

SystemCode 'error; 

1nt 'status; 

Execl ( ) calls ExecProgram( ) (and thus waits for the program created to finish executing, if status is 
non-NULL). It returns the program exit status in status and a system status code error (which indicates 
the nature of any errors encountered in Execl itself). Input, output, and errput arc used to specify the 
standard I/O of the program to be loaded and run. The remaining fields of the root message passed to 
ExecProgram() are derived from the invokcr's root message. argO actually represents the first of a 
variable number of parameters that represent the arguments to be passed to the new program. It is the first 
element of the argv array passed to ExecProgram( ). 



1nt system(cmd) 
char *cmd; 

Invokes an 

exec -c 
on the and string. The program's exit status is returned. 
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This chapter outlines the facilities available to programs for interacting with the user— via the workstation 
agents. The manner in which this interaction is manifested to the user was discussed in Chapter 2. 
Implementation details of the various workstation agents may be found in Chapters 44, 46, and 45. 

The discussion here is broken down into two basic components: terminal emulation and graphics. The 
terminal emulation facilities support ANSI virtual terminals and are common to all configurations of the 
V-Systcm — that is, to both the STS and the VGTS. Indeed, virtually all applications use these facilities, in 
lieu of or in addition to any graphics facilities they employ. That is, each executive is associated with a 
separate AVT and any application created by that executive inherits access to the same AVT. 

The graphics facilities are provided only by the VGTS. Attempts to use them in conjunction with the STS 
will fail. 

Warning: Take special note of the "warning" in the Preface! 

29.1 . Virtual Terminal and View Management 

Several routines for applications' manipulation of virtual terminals and views follow. All of tficsc routines 
may be used with respect to any type of virtual terminal, although some arc more useful for one type of 
virtual terminal than for other types. The virtual terminal identifier, vt, used in all routines is equal to the 
value returned by CreateVGT( ) or to the f Held field of the file descriptor returned by OpenPad( ) or 
0penAndPos1t1onPad(). These type-dependent routines, and others, are presented in subsequent 
sections. 



1nt' DeleteVGT(vt) 

short vt; 
Destroy the virtual terminal identified by vt. All the views associated with the virtual terminal will also be 
destroyed. 

Note: Badly named, since it may be used with A VTs as well as SG VTs (a.k.a. VGTsX 



1nt DefaultV1ew(vt, width, height, wXrrrtn, wYmln, 
zoom, showGMd, pWldth, pHelght) 

short vt, width, height, wXnrin, wYmln, zoom, showGMd; 

short •pkhdth, *pHe1ght; 
Create a view of the virtual terminal identified by vt, with the user determining the position on the screen 
with the graphical input device (mouse). The width and height parameters give the initial size of the 
viewport if they arc positive; non-positive values indicate that the user should determine the size with the 
mouse at run-time. Note that these arc physical device coordinates, not normalized device coordinates. 
wXmln and wYmln arc the world coordinates to map to the left and bottom edges of the viewport. If the 
pWldth and pHelght pointers arc non-NUi.L. then the shorts that they point to receive the selected width 
and height. Returns negative on error. Sec Chapter 2 for more information about how this call is manifested 
to the user. 
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zoom and showGMd are relevant only to SGVTs. zoom is the power of two to multiply world 
coordinates to get screen coordinates; it may. be negative, to denote that a view is zoomed out If showGr 1d 
is non-zero a grid of points every 16 pixels is displayed in the window. 

Note: In general this routine is not particularly well-suited to creating views of AVTs, as explained in the following section. 



1nt CreateV1ew(vt, sxmln, symln, sxmax. syntax, 
xm1n, wymin, zoom, showGMd) 
short vt; 

short sxmln, symln, sxmax, symax, wxmln, wymin , zoom; 
BOOLEAN showGr 1d; 

Create a view of the virtual terminal identified by vt — without interacting with the user. The initial position 
and size are determined by the sxmln, symln, sxmax and symax parameters, wxmln and wymin are the 
world coordinates to map to the left and bottom edges of the viewport. Returns negative on error. 

The zoom factor is the power of two to multiply world coordinates to get screen coordinates. The zoom 
factor may be negative, to denote that a view is zoomed out. If showGr 1d is non-zero a grid of points every 
16 pixels is displayed in the window. Again, these parameters arc relevant only for SGVTs. 

Note: In general this routine is not particularly well-suited to creating views of AVTs, as explained in the following section. 

We now proceed with the description of the terminal emulation and graphics facilities. In the process the 
differences between the two underlying types of virtual terminals should become clear. 

29.2. ANSI Terminal Emulation 

ANSI terminal emulation is provided by what we call ANSI virtual terminals (AVT). An AVT emulates a 
(almost complete) subset of ANSI standard X.64 — often equated with the Dec VT-100; the precise subset is 
given in Chapter 46. An application may use the ANSI terminal protocol to communicate with the 
workstation agent, including escape sequences for cursor control. Additional V-spccific support is provided 
for graphics input and line-editing, but applications may ignore these features as they wish. 

The "store" of an AVT is referred to as a pad. Conceptually, a pad may be of infinite size, allowing an 
application to store arbitrary amounts of data and allowing a user to scroll back and forth through this data. 
In current practice, a pad provides only enough storage for one "page" of data — one virtual screen- or 
viewport-full. Consequently, it is not particularly useful to create multiple views of a pad. 

Note: Unfortunately, the term "pad" has been adopted to mean both pad and AVT. Hence, most routines specific to AVT 
employ Pad in their names rather than AVT. Consequently, in the following discussion the terms are used interchangeably. 

29.2.1. Cooking Your AVTs 

The following mode bits arc maintained for each AVT to indicate the degree of "cooking" to be applied to 
I/O: 

CR_Input Change the CR (return) character to l.l- (UNIX ncwlinc) on input. This is for the benefit of 

UNIX programs which expect '\n' as a line terminator. 

DlscardOutputWhcn set, this bit causes all output to an AVT to be ignored. It is automatically set when 
the user types 'q' to an AVT that is blocked at the end of a page in PageOutput mode. It 
is automatically cleared whenever the workstation agent sends input to a program that is 
reading from the AVT. ITic bit may also be cleared "manually'* via Mod1fyPad(). In 
particular, application programs should call Modlf yPad( ) to clear this bit before sending 
a prompt to an AVT, to insure that the prompt is not discarded along with any previous 
output that was discarded at the user's request 
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Echo Echo in put characters. 

LF_0utput Change lf to CR-LF on output That is, every line-feed operation is preceded by a return. 

UneBuffer Wait for a line of input before returning. In addition, the line will be line-edited as 
described in section 2.5. 

NoCur s or Do not display a cursor in the indicated AVT. 

PageOutput Block the writer each time the AVT fills up with output, and wait for the user to issue a 
command which unblocks the AVT. The user interface to the this feature is described in 
section 2.6. This bit is 'on* by default 

PageOutputEnable 

Associated with each AVT is an internal flag, which, when 'off, disables turning on the 
PageOutput bit as described above. This internal flag is normally sticky, but can be 
changed by setting the PageOutputEnable bit in a Mod1fyPad() request In this 
case, the PageOutput bit is also used to set the new value of the internal flag. The 
PageOutputEnable bit should only be used by certain "privileged" programs, as a 
means of allowing the user to "permanentfy" disable paged output mode. 

ReportCUck Report "clicks" of the graphical input device — a press of at least one button, followed the 
release of all buttons — in response to requests for graphical events. 

ReportEscSeq Enable the "Emacs hack" described in Section 2.7. The encodings of the associated escape 
sequences arc presented in the next subsection. 

ReportTrans1t1on 

Report '"transitions" of the graphical input device — pressing or releasing any combination 
of buttons — in response to requests, for graphical events. 

By default keyboard input is line-buffered and echoed by the workstation agent with line-editing. More 
specifically, the following mode bits are set 

CR.Input 
Echo 

LF_0utput 
UneBuffer 

29.2.2. Encoding Graphical Input Events 

As noted, ReportEscSeq indicates that the application is capable of interpreting the associated escape 
sequences. 'ITiis allows many useful programs that deal with conventional terminals to be extended to take 
advantage of the graphical input capability — without major redesign. For example, an EMACS library can 
be loaded to bind these character strings to commands that position die cursor, set the EMACS mark, delete 
and insert text In fact these sequences were added precisely to support EMACS — which, unfortunately, 
affected their design somewhat 

The exact encoding of the escape sequences is given in Table 26-1, where <line> and <column> arc the 
position within die AVT where the mouse builon(s) were pressed — encoded as bytes. 

Nolc: Ihcsc arc escape sequences thai the workstation agent generates and the application must interpret The standard 
ANSI protocol contains escape sequences thai ihc application generates and the workstation agenl must interpret 

29.2.3. Functions 

Terminal emulation is implemented in terms of the standard V-Systcm I/O protocol as defined in Chapters 
22 and 33. For example, applications may read from and write to AVTs using the standard Read() and 
Wr1te( ) primitives. Consequently, the application interface to an AVT is through a V-Systcm file access 
descriptor (of type File). Hie following "AVT-speciFic" routines arc also provided: 
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Mouse 

Buttons Escape Sequence 

I M R 



x . A ESC M <lineXcolumn> 
x x . ESC M <lineXcotumn> null 
x . x ESCM<7/weXco/M/wi>CTRL-w 
. x x ESCM<lineXcolumn>CTRL-y 

Table 29-1: Encodings for graphical escape sequences. 

File •OpenPad(name, lines, columns, error) . 

char *name; 

short lines, columns; 

SystemCode *error; 
Create a new AVT and interact with the user to create a view of the AVT. name is a text name for the AVT. 
1 1 nes and col umns specify the size of the pad. Returns a pointer to a file access descriptor for the pad; 
NULL on an error, error is a pointer to the reply code. 

Note: The file descriptor returned is open for writing. If you want to read from it, you must use 0p«nF11e( ) to create 
another file descriptor with the same f 11«wvtr'(s workstation agent) and f lltld (= virtual terminal / AVT id). 

File *0penAndPos1t1onPad( name, x, y, lines, columns, error ) 

char •name; 

short x, y, lines, columns; 

SystemCode *error; 
Create a new AVT of size 1 1 nes and col umns, and place the view of this AVT at x, y. name is a text name 
for the AVT. Returns a pointer to a file access descriptor for the AVT; null on an error, error is a pointer 
to the reply code. 

Note: The note for OpenPad( ) also applies to OpenAndPosI t1onPad( ). 



Mod1fyPad(avt, mode) 
File »avt; 
1nt mode; 

Set the cooking mode of avt. mode is some combination of the bits described in the previous subsection. 



1nt QueryPad(avt) 
File *avt; 

Return the cooking mode of avt, some combination of the bits described in the previous subsection. 
Note: Rarely used, since its function is subsumed by QueryPadSlztQ. 



1nt QueryPadS1ze(avt, pUnes, pcols) 
File •avt; 
short *p!1nes, *pcols; 

Get the size and mode of avt. The number of lines and columns arc store in the shorts pointed to by 
pi 1 nes and pcol s, respectively. The cooking mode is returned as the value of the function. 
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PadF1ndPo1nt(avt, nllnes, x, y, pUne, pool) 
short avt, nllnes, x, y; 
short •pUne, *pcol; 

Convert the world coordinates (x,y) into a a line and column position within avt, stored in the shorts pointed 
to by pi 1 ne and pcol, respectively. 

Note: The avt parameter is currently unused, and the number of lines in the AVT must be specified in nl 1nts. 



RedrawPad(avt) 
File «avt; 

Redraw the indicated avt. 

Note: The same functionality should be available for SG VTs, but isn't 



SystemCode Ed1tl_1ne(avt, string, count) 
File *avt; 
char *string; 
1nt count; 

Enter line-editing mode in avt, as defined in Section 2.5. The line-edit buffer is pre-loaded with the first 
count characters of string. On return, string will contain the line-edited input Function returns one 
of the standard system reply codes. 

29.3. Graphical Output 

The central graphical concept of the VGTS is that application programs should only have to deal with 
creating and maintaining abstract graphical objects. The details of viewing these objects are taken care of by 
the VGTS. This is in contrast to traditional graphics systems in which users perform the operations directly 
on the screen, or on an area of the screen referred to as a viewport or window. Thus the VGTS deals with 
declarative information rather than procedural; you describe what the objects arc rather than how to draw 
them. 

The abstract graphical objects created and manipulated by a program arc stored in a structured display file 
(SDK). An SDK is a name space in which graphical items and symbols arc defined: it may be thought of as the 
"store" of a virtual terminal. 'Hie SDK is structured as a hierarchy, a directed acyclic graph of symbols calling 
other symbols. A symbol is an interior node of the graph, a logical grouping of graphical information. The 
leaves of the graph consist of graphical primitives such as rectangles, lines, or pieces of text An item may be 
cither one of these primitives or a call to another symbol — the "call statement" itself, not the symbol 
definition. Regardless, every item is contained in some symbol. 

Note that a symbol call is like a procedure call, not like a macro. Changing the symbol definition changes 
all instances. 

linen symbol is defined within its own 2-dimensional integer world coordinate space — although the 
dimensions of that coordinate space arc the same across all symbols, namely, -32768 to 32767. Translation is 
the only modeling transformation permitted on "called" symbols. All other transformations, such as rotation 
or projection from higher dimensions, must be handled by the application. 

As discussed in the previous section, defining symbols and filling them with items docs not make anything 
appear on the screen. In order for a symbol to appear, it must be displayed on a structured graphics virtual 
terminal (SGVY). An SGVIf may be thought of as a large, two-dimensional, imaginary display surface upon 
which graphical objects may be displayed. As for symbols, its coordinate space is from -32768 to 32767 in x 
and y, vastly larger than the actual screen. On this display space, one symbol in the SDK is displayed as the 
top-level symbol. Kvcry item that is in that symbol, or in any symbol called by that symbol, etc., will be 
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displayed on the SGVT. An item in a symbol that is called several times, will be displayed several times. 
Thus for example, in our SGVT we might display a bicycle as the top-level symbol. The bicycle symbol 
contains a call to the frame symbol, and two calls, with different coordinates, to the wheel symbol. The wheel 
symbol contains several items: a circle for the rim and lines for the spokes. Each of these items will be 
displayed twice, once for each wheel, though they were defined only once. 

29.3.1. SOF Manipulation 

29.3.1.1. Item Attributes 

Each item has the following attributes, as used in many of the procedures discussed below: 

Item A 16 bit unique (within the SDF) identifier for this object, or zero. This identifier is 

assigned by the program, guidelines for which are given in Section 293.1.4. 

type One of the predefined primitive types described below. Currently eight bits are allocated 

for this. 

typeData Eight bits of type-dependent information, as described in the next section. 

xm1 n, xmax, ym1 n, yraax 

Typically used to define die bounding box (or extent) of the item, in world coordinates. 
Also may be used for additional purposes, as discussed in the next section. Stored as 16-bit 
signed integers. 

Note: These names are misleading, since the VGTS actually sorts the endpoints and calculates the 
bounding box correctly. 

string A "string's" worth of type-dependent information, as described in the next section. 

29.3.1.2. Primitive Item Types 

Some of the meanings of the fields above depend on the type of the item. The following arc the types of 
primitive items that occur in a structured display file, with their type-dependent uses of the various attributes: 

SDF_CIRCLE A circle, centered at (xm1 n,ym1 n ) with a radius given by the typeData field. 

Note: This item type is currently supported only Tor the Sun model 100 framebuffer. 

SDF_FILLED_RECTANGLE 

A filled rectangle. typeData determines the pattern. There arc two possible sets of 
patterns, each influenced by the application for which they were developed. The first set 
was defined for a VLSI layout editor and is not likely to be of general use; they arc defined 
in <Vgts . h>. The second set was defined for a document illustrator and arc likely to be 
of greater interest; they arc defined in <sp!1nes.h>. To use one of them for a filled 
rectangle, add its index (as defined in <spl 1nes . h>) to the constant STIPPLEOFFSET 
(defined in <Vgts . h>, and use the resulting value as typeData. 

SDFJ3ENERALJ.INE 

A generalized line, from (xm1n,ym1n) to (xmax^max). 

SDF_H0RIZ0NTAL_LINE 

Horizontal line from (xm1 n,ym1 n) to (xmax,yra1 n). ymax is ignored. 

SDF_H0RIZ0NTAI_REF 

A horizontal reference line at (ymln + ymax / 2). Reference lines consist of a thick line 
with two tick marks at the ends, and some associated text They arc intended for use in 
computer aided design applications like the dale layout editor. 

SDF J3UTLINE Outline for a selected symbol. xm1 n, xmax, yral n and ymax give the box for the outline. 
typeData specifics flag bits to select each of the edges: LeftEdge, RlghtEdge, 
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TopEdgo or BottomEdge. 

SDF_P0INT A point, which usually appears as a 2-by-2 pixel square at (xm1 n,ym1 n). 

SDF_POLYLINE A poly-line, consisting of a connected set of line segments., siring points to an array of 
points, as in: 

typedef struct 

{ 

short x; 

shor y; 
} SdfPoInt; 

Noite: This item type is currently supported only for the Sun model 100 framebuffer. 

SDF_RASTER A general raster bitmap with a lower left corner at (xnil n,ya1 n) and upper right corner at 
~ (xmax,ymax). typeData determines if the raster is written with ones as black or white. 

string points to the actual bitmap, in 16 bit- wide swaths. 

Note: On the Sun model 100 framebufler, a raster can be displayed at zoom factors 0. 1, 2, 3, and 4 
(only): on the model 120 framebufler. only zoom factor (no magnification) is currently supported. 
In all cases, the VGTS only supports the "display" of bitmaps, not any operations on them An 
application-level libary containing "RasterOp" routines is, however, available (see Section 29.8). 

SDF_SEL_HORIZ_REF 

A thick (selected) horizontal reference line at (ym1 n + ymax / 2). 

SDF_SEL_VERT_REF 

A thick (selected) vertical reference line at (xm1 n + xmax / 2). 

SDF_SIMPLE_TEXT 

A simple text suing employing a fixed-width font (typically 8 pixels wide by 16 pixels 
high). The lower left corner of the string will be placed at (xm1n.ym1n). The values of 
xmax and ymax need not surround the text, but they arc used as aids for redrawing, so 
should correspond roughly to the real bounding box. 



SDF_SPLINE 



A spline object, of which a special case is a polygon. Splines may be filled with any of a 
number of different patterns or drawn with any of a number of different "nibs", as defined 
in <sp11nes.h>. string points to a SPLINE structure as defined in the 
<sp11nos.h>: 



typedef struct 

{ 

short x, y; 










} POINT; 






typedef struct 

{ 

unsigned short 




- 


order; 


/* 


unsigned short 


numvert 


;/* 


enum N1b 


nib; 


/• 


unsigned short 


border; 


/• 


unsigned short 


closed; 


/• 


unsigned short 


filled; 


/* 


unsigned short 


opaque; 


/* 


enum Pattern 


pat; 


/* 


POINT 


head; 


/* 


} SPLINE; 







SDFTEXT 



Order of the spline */ 
Number of vertices present. */ 
N1b to be used for drawing. */ 
Is the border visible? */ 
Is this object closed or open?*/ 
Is this object filled? •/ 
Is the filling opaque (solid)?*/ 
Fill (stipple) pattern. •/ 
Head of the 11st of vertices */ 



Note: The patterns used for splines arc a subset of those used for filled rectangles. (Sec the 
discussion of SDF.FILLEDJlECTAfiGLE above.) 

A string of general text, with die left end at xmln and the baseline at ymln. typeData 
determines the font number. (To get the actual bounding box (calculated from 
information in the font file), use Inqu1reltem() after die Addltem(), as defined in 
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the following section.) See section 29.3.3 for an example. 

SDF_.VERTICALJ.INE 

Vertical line from (xm1 n,ym1 n) to (xmi n,ymax). xmax is ignored 

SDF_VERTICAL_REF 

A vertical reference line at (xm1 n + xmax / 2). 

29.3.1.3. Functions 

The following arc the currently defined functions used to manipulate an SDF and, hence, generate 
graphical output All return values except the actual function value arc passed via pointer parameters. If any 
pointer is null, no value is returned for that parameter. For performance reasons, many of these calls are 
batched (several calls in one request) and/or pipelined (no return values). In cither case there are no 
meaningful return values and any error conditions simply cause the VGTS to drop the call on the floor. The 
description for each routine indicates whether this is the case. 



short CreateSDF() 

Create a structured display file, returning its id. Returns -1 if the VGTS runs out of resources. Must be called 
before any symbols are defined. Forces all pending calls to be executed. 



1nt DeleteSDF(sdf) 
short sdf; 

Return all the items defined in the given sdf to free storage. This includes all data structures associated with 
items in the SDF. Returns sdf or -Ion error. Forces all pending calls to be executed. 



Def1neSymbo1(sdf , symbol, textName) 
short sdf, symbol; 
char ♦textName; 

Enter symbol into the sdf and open it for editing. Only one symbol may be open in any given SDF at a 
time. textName is an optional descriptive name for the symbol, used in the hit selection routines for 
disambiguating selections. Buffered call, but always returns symbol for backward compatibility. 



short EndSymbo1(sdf , symbol, sgvt) 
short sdf, Item; 
short sgvt; 

Close symbol in sdf so no more insertions can be done and cause all views of sgvt displaying the symbol 
to be redrawn. Hie VGTS ensures that, if only additions have been made since the last EndSymbol, only 
those additions arc drawn. Called at the end of a list of Addltem() and AddCall() calls defining a 
symbol, started with Def 1neSymbol() or Ed1tSymbol(). Forces all pending calls to be executed. 
Always returns symbol for backward compatibility. 

Nole: syabol is actually redundant, since only one symbol can be "open" in any SDF at a time, bul it must be provided. 



Ed1tSymbol(sdf , symbol) 
short sdf, symbol ; 

Open (already existing) symbol in sdf for modification. This has the effect of calling Def IneSymbol ( ) 
and inserting all the already existing entries. The editing process is ended in the same way as the initial 
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definition process — a call to EndSymbol(). Buffered call, but always returns symbol for backward 
compatibility. 



short DeleteSymbol(sdf , symbol) 
short sdf,. symbol; 

Delete symbol from sdf. More correctly, render the symbol definition "empty" to prevent problems with 
dangling references (calls) to the definition. The dangling references will be interpreted but will have no 
effect, since the symbol will no longer contain any items. Returns symbol if successful, else 0. Forces all 
pending calls to be executed. 



Addltem(sdf, Item, xsnln, xmax, ymln, ymax, 
typeData, type, string) • 
short sdf, item, xmln, xmax, ymln, ymax; 
unsigned char type, typeData; char *str1ng; 

Add Item to the currently open symbol in sdf. Remaining parameters as defined above (Sections 29.3.1.1 
and 29.3.1.2). Buffered call, but always returns 1 tern for backward compatibility. 



AddCall(sdf, Hem, xoffset, yoffset, calledSymbol) 
short sdf, Hem, xoffset, yoffset, calledSymbol; 

Add an instance of the calledSymbol to the currently open symbol in sdf. The "call statement" itself is 
given the name Hem. The origin of the called symbol instance is placed at (xoffset,yoffset) in the 
coordinate space of the calling symbol. May be called before the called symbol is defined, in which case a 
dummy entry for the symbol is inserted in the SDF; any future attempts to define the symbol will use the 
dummy entry. Buffered call, but always returns 1 tern for backward compatibility. 



Deleteltem(sdf , Hem) 
short sdf. Hem; 

Delete Hem from the currently open symbol in sdf. Symbol calls can be deleted just like any other item, 
but symbol definitions arc deleted by the DeleteSymbol () function. Buffered call, but always returns 
1 tern for backward compatibility. 



1nt Inqu1reltem(sdf , Hem, xmln, xmax, 

ymln, ymax, typeData, type, string) 
short sdf, Hem; short *xm1n, *xmax, *ym1n, *ymax; 
unsigned char Hype, UypeData; char *str1ng; 

Read the attributes of Hem in sdf. Parameter semantics arc defined above (Sections 29.3.1.1 and 29.3.1.2). 
All parameters except sdf and Hem arc pointers. For each non-null pointer, the value of the field for that 
item is returned. Zero is returned if the item could not be found; otherwise, non-zero. Forces all pending 
calls to be executed. 



short Inqu1reCall(sdf , Hem) 
short sdf, Hem; 

Return the name of the symbol called by Hem in sdf. Returns zero if the item is not a call, or could not be 
found. Forces all pending calls to be executed. 
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Changeltem(sdf , Item, xmln, xmax, 

ym1n, ymax, typeData, type, string) 
short sdf, Item, xmin, xmax, ymln, ymax; 
unsigned char type, typeData; char *str1ng; 

Change the parameters of (already existing) Item in sdf. Remaining parameters as defined above (Sections 
29.3.1.1 and 29.3.1.2). This is equivalent to deleting an item and then reinserting it, so the item must be part 
of the open symbol. Buffered call, but always returns item for backward compatibility. 

29.3.1.4. Naming Items and Symbols 

Items and symbols are both identified by 16-bit identifiers, most commonly thought of as unsigned integers. 
The identifiers are specified by the application. It is assumed that the application will maintain some 
higher-level data structures, along with the appropriate mapping to these internal item names. Items that will 
never be referenced can be given item number zero. The item names are global to each SDF, so the 
programmer should be careful not to assign the same item number within the same SDF twice. However, 
applications may use multiple SDFs for multiple name spaces. 12 

For example, a picture of a bicycle might define a symbol for a wheel This definition of the wheel symbol 
is given item number 4. There may then be two instances of item number 4, that are given item numbers 5 
and 6. The individual spokes of the wheel arc components of symbol number 4, but arc all given item 
number 0, since we will never want to refer to any of them. If it is desired to delete or move any individual 
spoke, then the items may be given numbers, 

29.3.1.5. Output Modes 

By appropriate use of the various functions, programs may achieve the effect of deferral modes for 
graphical output. First, they may construct graphical objects in their entirety and then display them, by 
executing a Def 1neSymbol() or Ed1tSymbol(), followed by many Addltem() or AddCa11() calls, 
followed by an End Symbol ( ). This corresponds to creating an "invisible segment" and then displaying it in 
traditional graphics systems. 

Alternatively, an application many construct and display an object "on the fly", that is, display each item as 
it is added to the object This is done, for example, by repeatedly executing an Ed1tSymbol() - 
Addltem() - EndSymbol() sequence, such that each EndSymbol() causes the symbol to be redrawn. 
This corresponds to creating a "visible segment" in traditional graphics systems. (Note the optimization 
discussed in the description for EndSymbol ( ), which reduces redraw time.) 

The first style of output yields higher throughput, whereas the second yields faster response. 

29.3.1.6. An Example 

To create the bicycle figure of the previous section, we would use code like the following: 



12 The intended use of multiple SDFs is that an application would have both "private" and "shared" graphical data, such that the 
shared data was stored in an SDF used by multiple (cooperating) applications. 
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short sdf; 

sdf - CreateSOF(); 
0ef1neSymbo1(sdf. 4, "Wheal"); 

Addltem(sdf, 0. xmln, xmax, ymin, ymax. 0, SDFJSENERALJ.INE, NULL); 

(add the components of the wheel symbol) 

EndSymbo1(sdf , 4, 0); 

Def1neSymbol(sdf . 3, "Bicycle"); 
AddCall(sdf, 5, xl, ymln, 4); 
AddCall(sdf. 6, x2, ymln. 4); 
EndSymbol(sdf , 3, 0); 

(whoops . . . forgot the frame) 
Ed1tSymbol(sdf, 4) 

(add frame) 
EndSymbol(sdf. 4, 0) 

29.3.2. SGVT Management 



1nt CreateVGT(sdf ( type, topSymbol, string) 

short sdf; 1nt typo; short topSymbol; char *str1ng; 

Create an SGVT of the indicated typo. Put the indicated symbol — topSymbol in sdf — as the top-level 
symbol in the SGVT. topSymbol can be zero to indicate a blank SGVT. type can be some combination of 
TTY, GRAPHICS, and ZOOMABLE, but programmers arc advised to use the terminal emulation functions 
described above for TTY's. If the ZOOMABLE bit is set, the view zooming factor can be changed by the user. 
Returns the virtual terminal id or negative on errors. 



D1sp1ayltem(sdf , topSymbol, sgvt) 
short sdf, topSymbol; 1nt sgvt; 

Change the top-level symbol for sgvt to topSymbol in sdf. The new symbol is displayed in every view of 
the SGVT. 

29.3.3. Defining and Using Fonts 



short Def1neFont(name, flleName) 
char ♦name, *f11eName; 

Defines a font to be used in subsequent SDFTKXT items. 'Hie name is a pointer to a string giving the name 
of the font, for example, "Helvetica 10B". The font is read by the VGTS from the file with the pathname 
given as the second argument 'Hie flleName argument can be null to indicate a read from the standard 
place. The font-id returned by this call is used as the typeData field for SDHTEXT items. A negative 
return value indicates an error. For example, 

short roman ■ DefineFont("T1mesRomanl2 N t NULL); 
Addltem(sdf, 0, x, x, y. y, roman, SDF_TEXT, "Hello") . 

will display the string "Hello" in the Times Roman font at 12 point size, at the position (x,y) on the screen. 
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29.4. Graphical Input 

The VGTS maintains an event queue for each virtual terminal — whether AVT or SGVT— on which both 
graphical (mouse) and keyboard events are queued 

29.4.1. Common Functions 

The following functions arc (more or less) independent of the type of virtual terminal. To maintain 
compatibility with the AVT-spccific routines and the V I/O protocol, the desired virtual terminal must be 
bound to a V file access descriptor before calling these functions. Specifically, in the descriptions below, 
vt->f Heserver must contain the process id of the workstation agent and vt->f Held must contain the 
id of the virtual terminal. The file descriptor returned from OpenPad( ) is set up precisely in this fashion, 
but if CreateVGT( ) is used, the application must explicitly construct an appropriate file descriptor, storing 
the result of CreateVGT( ) in vt->f Held. The file pointer stdln may be used to receive input from the 
virtual terminal (usually an AVT) associated with the application's "standard input". 



GetEvent(vt, px, py, pbuttons, cbuf) 
File *vt; 

short *px t *py, *pbuttons; 
char *cbuf; 

Wait for any input event in the indicated virtual terminal. This currently means mouse clicks, mouse 
transitions, or keyboard input — not mouse movements. If the virtual terminal is an AVT, then the type of 
graphical event reported depends on the cooking mode of the AVT. Returns the world X and Y coordinates 
of the mouse in the shorts pointed to by px and py, and the buttons in the short pointed to by pbuttons if 
the event is graphical or else returns the characters in the buffer pointed to by cbuf. The function value is 
negative on error (in which case, vt->1astexcept1on contains the error code), on mouse event, or the 
number of characters returned on a keyboard event. 

Note: At most lO.MSG.BUFFliR (defined in <V1oprotocol .h> - currently 20) characters will be returned in cbuf. 
The corresponding actual parameter should be (at least) this size. 



1nt GetGraph1csEvent(vt, px, py, pbuttons) 
File *vt; 
short *px, *py, *pbuttons; 

Wait for a graphical event in the virtual terminal associated with the file descriptor vt. Currently, graphical 
events consist of transitions and clicks of the mouse buttons — not movements. If the virtual terminal is an 
AVT, then the type of graphical event reported depends on the cooking mode of the AVT — which must be 
set appropriately via Modify Pad ( ). Returns the world X and Y coordinates in the shorts pointed to by px 
and py; the state of the buttons is returned both in the short pointed to by pbuttons and as the value of the 
function. The function value is negative on error, in which cast vt->1astexcept1on contains the error 
code. 



1nt GetGraph1csStatus(vt, px, py, pbuttons) 
File *vt; 
short •px, *py, *pbuttons; 

Sample the graphical input device relative to the virtual terminal associated with the file descriptor vt. 
Currently, this means returning the current location and button status of the mouse, whether or not the mouse 
currently resides in a view of the virtual terminal and without waiting for the mouse to move. All events 
queued for the virtual terminal arc Hushed prior to sampling. Returns the world X and Y coordinates in the 
shorts pointed to by px and py; the state of the buttons is returned both in the short pointed to by 
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pbuttons and as the value of the function. The function returns negative on error, in which case 
vt->l astexcept 1on contains the error code — typically EOF to indicate that the mouse cursor was not in 
a view of the virtual terminal. 

29.4.1 .1 . Antiquated Routines 

The following routines pre-date those listed above. The only reason for their continued existence is that 
they currently arc the only graphical input routines that may be employed by applications running on non-V 
hosts (see Section 29.7.2). However, their days arc numbered. 



short GetMouseC11ck(x, y, buttons) 
short *x, *y, 'buttons; 

Wait for a mouse click in the virtual terminal corresponding to stdln. The world X and Y coordinates are 
returned in the shorts pointed to by x and y, and the state of the buttons is returned in the short pointed to by 
buttons. If a key is pressed, a message is printed stating that a mouse click is expected, and the key is 
ignored. Forces all pending calls to be executed and blocks until a mouse click does come in. 

Note: This function is scmantically equivalent to both GetG>raph1csEvent() and G«tMous«OrK«yboard() (where 
any character returned is dropped on the floor). 



short GetMouseOrKeyboard(c, x, y, buttons) 
short *x, *y, 'buttons; 
char *c; 

Wait for a mouse click or keyboard press in the virtual terminal corresponding to stdln. Ff the mouse is 
clicked, the world X and Y coordinates arc returned in the shorts pointed to by x and y, the state of the 
buttons is returned in the short pointed to by buttons, and the function returns the identifier of the virtual 
terminal in which the click occurred. If a key was pressed, the character is returned in the location pointed to 
by c, and the function returns 0. 

Note: litis function is scmantically equivalent to GetEvant( ), 

29.4.2. SGVT-oniy Functions 

Mouse events often signify an attempt on the part of the user to "select" some graphical object. When such 
an event is reported to the application, it should respond by calling the following function to determine 
which, if any, graphical object was so selected. 



LISTTYPE F1ndSe1ectod0bject(sdf , x, y, sgvt, searchType) 
short sdf, x, y„ sgvt; 
char searchType:; 

Return a list of items that arc at or near (x,y) in sgvt. Along with each item is a set of edges, to indicate that 
the hit was near one or more edges of the object. 'ITic searchType selects one of several modes of hit 
detection: 

Al 1 Anything will do. 

All Lines Any lines. 
JustHortz Just horizontal lines. 
JustRasters 

Just rasters. 
JustRects Just rectangles. 
JustSpHnes 
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Just splines. 
JustText Just text strings. 
JustVerts Just vertical lines. 

Usually the constant value Al 1 will be used. The return value is defined as follows: 

typedef struct MlnElement 

short Item; 

short edgeset; 

struct HlnElement *next; 
} MINREC, *MINPTR; 

typedef struct Mstlnfo 

{ 

MINPTR Header: 

short NumOfElements; 

} LISTTYPE; 

29.5. Miscellaneous Functions 

The following functions arc (more or less) independent of the type of virtual terminal — despite the 
occurrence of Pad, or Vgt in their names. As in Section 29.4.1, to maintain compatibility with the AVT- 
specific routines and the V I/O protocol, the desired virtual terminal must be bound to a V file access 
descriptor before calling these functions. Specifically, in the descriptions below, vt->f lleserver must 
contain the process id of the workstation agent and vt->f 1le1d must contain the id of the virtual terminal. 
The file descriptor returned from OpenPad( ) is set up precisely in this fashion, but if CreateVGT{) is 
used, the application must explicitly construct an appropriate file descriptor, storing the result of 
CreateVGTQ in vt->f 1le1d. The file pointer stdln may be used to receive input from the virtual 
terminal (usually an AVT) associated with the application's "standard input". 



GetTTY() 

Put the terminal in raw mode. The (remote) UNIX version of this routine docs the appropriate UNIX operation 
if standard input is a tty device, otherwise it sends the proper code for the remote execution facility. 

short popup(menu) 

PopUpEntry menu[]; 

Display a "pop-up" menu and wait for the user to select an option. The menu argument points to an array of 
Pop Up En try structures: 
typedef struct 

char 'string; /• String to display. •/ 

unsigned char menuNuraber; /* Number returned 1f entry selected. */ 
} PopUpEntry; 

The array is terminated by a null string. The code of the menu item selected by the user is returned. If the 
user clicks outside the menu, a negative value is returned. 



ResetTTY() 

Restore the mode before the last GetTTY( ). Runs under UNIX as well, checking standard input properly. 
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SelectPad(vt) 
File *vt; 

Cause the virtual terminal associated with vt to be selected for input The (principal) view of the virtual 
terminal is brought to the top of the stack of views. Only works if the calling program also "owns" the virtual 
terminal currently selected for input 



SystemCode SetVgtBanner(vt, name) 
File *vt; 
char *name; 

Set name to be the banner at the top of each view of the virtual terminal corresponding to vt. 

29.6. Example Program 

The following program can be compiled to run cither remotely under Unix or under the V system. The 
#1f def VAX directives allow the programmer to conditionally compile code for one environment or the 
other. It first creates an SDF and SGVT, then displays 100 random objects of various kinds. 

* test.c - a test of the remote VGTS implementation 

* Bill NowicM September 1982 
•/ 

^include <Vgts.h> 
^Include <Vio.h> 

#define Objects 100 /• number of objects */ 
short sdf, sgvt; 

Qu1t() 

{ 

DeleteVGT(sgvt.l); 

DeleteSDF(sdf); 

ResetTTY(); 

ex1t(); 
} 
ma1n() 

{ • 
1nt 1; 
short Item; 
long start, end; 

#1fdef VAX 

prlntf ("Remote VGTS test program\n"); 
#else VAX 

prlntf ("VGTS test program\n"); 
#endif VAX 

ff lush(stdout); 

GetTTY(); 

sdf - CreateSDF(); 

Def 1neSymbo1( sdf, 1, "test" ); 

Addltem( sdf. 2, 4, 40. 4, 60, NM, SDF„FILLED_RECTANGLE. NULL ); 

EndSymbo1( sdf, 1, ); 

sgvt - CreateVGT(sdf. GRAPHICS+ZOOMABLE. 1, "random objects" ); 

Defau1tView(sgvt, 500, 320, 0, 0, 0, 0, 0, 0); 
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t1me(&start); 

for (1-12; 1<0bjects; 1++ ) 

{ 

short x - Random( -2, 155); 
short y ■ Random( -10, 169); 
short top ■ y + Random( 6, 100 ); 
short right ■ x + Random( 4, 120 ); 
short layer ■ Random( NM, NG ); 

Ed1tSymbo1(sdf. 1): 
De1eteltem( sdf, 1-10); 
switch (Random(l, 6) ) 

case 1: 
Addltem( sdf, 1. x, right, y, top, layer, 

SDF_FILLED_RECTANGLE, NULL ); 
break; 

case 2: 

Addltera( sdf, 1, x, x+1000, y, y+16, 0, SDF.SIMPLE.TEXT, 

"Here 1s some simple text" ); 
break; 

case 3: 

Addltem( sdf, 1, x, right, y, y+1, 0, 

SOF_HORIZONTALJ.INE, NULL ); 
break; 

case 4: 

Addltem( sdf, 1, x, x+1, y, top, 0, 

SDF_VERTICALJ.INE, NULL ); 
break; 

case 5: 

Addltem( sdf, 1.x, right, y, top, 0, 

SDFJ5ENERALJ.INE, NULL ); 
break; 

case 6: 

Addltem( sdf, 1, x, right, top, y, 0, 

SDFJ3ENERALJ.INE. NULL ); 
break; 

} 
EndSymbo1( sdf, 1, sgvt ); 

} 

t1me(&end); 

1f (end—start) end ■ start+1; 

pr1ntf("Xd objects 1n Xd seconds, or Xd objects/second\r\n", 

Objects, end-start, Objects/(end-start)); 
pr1ntf("Donet\r\n"); 
Qu1t(); 



} 



Random( first, last ) 

{ 

/* 

* generates a random number 

* between "first" and "last" Inclusive. 
•/ 

1nt value ■ rand()/2; 
value %■ (last - first + 1); 
value +■ first; 
return(value); 
} 
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29.7. Some Logistics 

The constants for mouse search types, virtual terminal usage types, etc. are found in the include files 
Vgts . h and Vtormagent . h. 

29.7.1. Applications Running Under V 

The stub routines are available in the default V library, so just including the option -V on your cc68 
command line for linking should work. Do not include the -1 VGTS option on your command line. 

29.7.2. Applications Running Under Other Operating Systems * 

To transparently run programs on a Unix system, use -1VGTS on your cc command line. Use 
-I/usr/sun/1 ncl ude to get the file Vgts . h. 

This package employs escape sequences that can be used through PUP Telnet, IP Telnet, or with the remote 
command execution facility of the executive. The details of this protocol arc explained in Chapter 46. 

Note: The following functions arc not currently available to applications in this class: 
EdHL1nt() 
G«tEvtnt( ) 
G«tGraph1csEvtnt( ) 
6etGraph1csStatus() 
ModffyPad() 
OpenPad() 
Qu«ryPad() 
QueryPadS1z«() 
RedrawPad() 
S«1«ctPad() 
SetVgtBanner() 

29.8. Rolling Your Own 

The primitives discussed here have proven suitable to a wide range of applications. Naturally, a few users 
have found them unsuitable, especially for applications that manipulate large bitmaps, such as image 
processing applications. Although a raster item type is supported, raster operations arc not. Hence, 
applications must perform the operations themselves and then pass the new bitmaps to the VGTS. 
Subsequent versions of the VGTS will address these and similar problems. 

In the meantime, desperate programmers may, in fact, manipulate the frame buffer directly by using the 
low-level device-dependent graphics libraries employed by both the VGTS and the STS. There is a separate 
library for each real device. 'ITic libraries and their documentation may be found in the 11bc/graph1cs 
directory. 

Note: As noted above, these libraries also contain a variety of device-independent routines, including some general-purpose 
" RastcrOp" routines, that may be of use to some applications. 

Warning: l>ircctly manipulation of me graphics hardware may be very hazardous to your health. On workstations with the 
Sun model I00 frame buffer, for example, your manipulation of the frame buffer may conflict with that of (he workstation 
agent, leading to rather odd screen images. That is, both your application and the workstation agent arc manipulating the 
frame buffer registers. Fortunately, in this case, you should be able to avoid most problems by rendering alt virtual 
terminals that arc generating output and all AVI s that have been selected for input invisible — by burying them under 
inactive virtual terminals, for example, The latter step is needed in order to disable the blinking cursor. 

Finally, if you still arc not dissuaded, consider that access to the frame buffer will be prevented in future versions of the 
system, hopefully coincident with the addition of suitable raster support to the VGTS. 
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30.1 . Time Manipulation Functions 

The time-related functions in the V C library arc described below. A few of them are not present in the 
Unix C library. 



unsigned GetT1me( clicksptr) 

return the current time in seconds as maintained by the local kernel. The current time is represented as 
seconds since January 1, 1970 GMT. If clicksptr is not nuix, the number of clicks since the last second is 
stored in location pointed to by clicksptr. The standard manifest CL1CKS_PER_SEC indicates the number 
of clicks per second for the host 



SystemCode SetT1me( seconds, clicks) 

sets the local kernel time to the specified seconds and clicks. The time maintained by the kernel is 
normally set on system boot and need not be changed subsequently. 

The standard time representation used is the number of seconds since January 1, 1970 GMT, plus the 
number of clock interrupts since the last second. 



unsigned Del ay (seconds, clicks) 

suspend the execution of the invoking process for the specified number of seconds and clicks, (where a click 
is a machine-specific unit, usually one clock interrupt). Del ay returns the number of clicks remaining in the 
delay period. ITius, it normally returns 0. However, if the delaying process is awakened using Wakeup, it 
may return a non-zero value. 



SystemCode Wakeup (p Id) 

unblock the process specified by p1d, returning OK, assuming the process is currently delaying using Delay 
and the invokcr is the same user as the specified process, or is a privileged user. Otherwise, the return value is 
a standard system code indicating the error. 



st1me(), t1me(), ftlme() 

These arc Unix system calls and arc implemented here with simple library functions which emulate the Unix 
functions by performing the appropriate V kernel operations SetT1me( ) and GetT1me( ). ITicy have the 
same interface and functionality as in Unix; however, f t1me( ) has the timczonc hardwired as Pacific Time, 
since the V-Systcm provides no time zone information. 



ct1me(), local t1me(), gmt1me(), asct1me(), t1mezone() 

These arc identical to the Unix library functions. 
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sleep(seconds) 

unsigned seconds; 

The invoking process is suspended from execution for the specified number of seconds. The actual time may 
be considerably longer than that specified if die process is not the highest priority ready process when its sleep 
time expires. s1eep() is not sensitive to Wakeup()'s. Use the V system call Delay() for a 
Makeup () -able suspension. 



unsigned GetRemoteT1me() 

Returns the time according to the TIME_SERVER in seconds since January 1, 1970, GMT. Returns zero if it 
fails, e.g., no time server responded. 

i ' 

30.2. Strings 

■ ;' 3 
The string-related functions in the V-Systcm C library are described below. 

30.2.1. Unix String Functions 

The following functions arc identical to the functions of the same name provided by Unix. See the Unix 
Programmer's Manual for documentation. 

atof() ato1() atol() crypt() 

ecvt() gcvt() index() rindex() 

strcat() strncat() strcmp() strnempj) 

strcpy() strncpy() strlen() 

30.2.2. Verex String Functions 

There is also another set of string manipulation functions which were ported from Verex. These include the 
following: 



1nt Any(c, string) 

char c; char *str1ng; 

Determine whether there is any occurrence of the byte c in die string string, and return true (nonzero) if 
so, else false (zero). 



char *Concat(dest, si, s2, s3) 
char *dest, *sl, *s2, *s3; 

Concatenate the strings si, s2, and s3, store the result in dest, and return dest. dest must have enough 
room to store the resulting string. If any of si, s2, s3 arc null pointers, the remaining arguments arc 
ignored. 



1nt Convert_num(str1ng, del 1m, base) 

char *str1ng; char **de11m; unsigned base; 

Parse die given string to extract a number of base base and return its value. If base is zero, the initial 
character of the string determines the base, as follows 

§ Base 2 
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(zero) Base 8 
$ Base 16 
otherwise Base 10 

Upon return, *del 1m is modified to contain a pointer to the delimiter that terminated the number. 



char •Copy_str(str1mg) 
char *str1ng; 

Copy the given string into a newly allocated region of memory and return a pointer to the copy. The new 
region is allocated using malloc( ) and may thus be freed using f ree( ) when the copy is no longer needed. 
The function strsave( ) is identical to Copy_str ( ). 



1nt Equal(sl, s2) 
char •si, *s2; 

Compare the strings si and s2. Return true (nonzero) if the strings are equal, else false (zero). Strings are 
considered to be equal if and only if they arc of equal length (up to the terminating null byte) and each 
corresponding byte is the same. 



1nt Hex_value(c) 
char c; 

Return the value of c, interpreted as a hex digit Return -1 if c is not a hex digit. 



char *Lower(str1ng) 
char *stp1ng; 

Convert all alphabetic characters in string to lowercase and return string. 



unsigned Null_stp(stp1ng) v 
chap *stp1ng; 

Return true (nonzero) if string is a null string (i.c., of length zero), else return false (zero). 



chap *Sh1ft_left(stPlng, chaps) 
chap *stp1ng; unsigned chaps; 

Delete the leftmost chaps characters of string by shifting the remaining characters to the left, and return 
string, string must be at least chars characters long, but this condition is not checked. 



unsigned S1ze(str1ng) 
chap *stp1ng; 

Return the number of characters in the given string, i.c, the index of the null byte that terminates the string. 



chap *Uppep(stPlng) 
chap *stp1ng; 

Convert all alphabetic characters in stPlng to uppercase and return string. 
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30.3. Exception Handling Functions 



short *StandardExcept1onHand1er(req, p1d, fout) 
register ExceptlonRequest *req; 

/* Exception message. •/ 
Processld p1d; /* Process Incurring exception. •/ 

File *fout; /* Print out messages on this file */ 

Standard exception handling print routine. Prints out some information about the process incurring the 
exception and returns the pc at which the exception occurred, req points to the exception request message, 
p1d is the process id of the process that incurred the exception, and fout is the file on which the message is 
to be printed. 



Pr1ntStackDump(fout, p1d) 

File *fout; Processld p1d; 

Prints out the stack of the process specified by p1d. The process must be in the same address space as the 
invoker. 

30.4. Other Functions 



qsort(base, nel, width, compare) 

char *base; 1nt nel, width; 1nt (*compare)(); • 

Implements the quicksort algorithm, base is a pointer to the base of the data; nel is the number of 
elements; width is the width of an clement in bytes; and compare is a function to compare two elements. 
The function compare must return an integer less than, equal to, or greater than zero, if the first argument is 
less than, equal to, or greater than the second, respectively. 



setjmp(env) 

jmp_buf env; 

longjmp(env, value) 

jmp.buf env; 1nt value; 
set jmp( ) saves the stack environment in env, so that a later call to longjmp( ) will act like a return was 
made from the function which contained the call to set jmp( ), with return value val ue. 



char *ErrorStr1ng(error) 
SystemCode error; 

Returns a pointer to a string describing the system request or reply code error, in human readable terms. 
Use this in error messages instead of printing the numeric value of the code. 



Pr1ntError(error, msg) 

SystemCode error; char *msg; 

Prints the string msg and an explanation of die SystemCode error on the standard error file. 
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All system services other than those implemented by the kernel are provided by sending a message to one of 
the system server processes. This part of the manual describes the various protocols for requesting these 
services, including the format of request and reply messages, the possible values for the message fields, and 
the server process that handles the request. A secondary role of this part of the manual is to act as an 
implementation guide to die various servers; at some future time, these implementation details will be 
removed to a separate manual. 

The information contained in this part of the manual is generally not required by application programmers 
because most protocols arc implemented in the standard C program library described in Part II of the manual. 
However, more sophisticated use of the system may require the more detailed information in this part of the 
manual 

This chapter gives an overview of the interactions among the different servers and the kernel. The next 
three chapters present the standard message formats and codes, and the details of two standard protocols, the 
V-Systcm I/O Protocol and V-Systcm Naming Protocol. The remaining chapters give the details of the 
individual servers, describing which of the standard protocols they implement, additional server-specific 
protocols they provide, and, in many cases, how they arc implemented. 

31 .1 . The Basic Servers - In Isolation 

Figure 31-1 shows the configuration of servers on a typical workstation. The various interactions indicated 
arc discussed in the following section. Here we discuss the basic functions and structure of each server more 
or less in isolation from the others. 

31.1.1. General Considerations 

There arc two basic dimensions by which servers may be classified: whether they arc implemented as 
pseudo-processes within the kernel or outside the kernel, and whether an instance of die server exists on each 
workstation or not Several servers arc implemented internal to the kernel primarily for performance reasons. 
Naturally, these servers must exist on every workstation. As discussed below, there arc several additional 
servers, including those that manage teams and exceptions, instances of which must also exist on every 
workstation. Other servers exist, however, that need not be resident on every workstation, the most common 
example being a storage server. 

Regardless of how (or where) servers arc implemented, they are always accessible via the usual IPC facilities 
and standard protocols. The "main" server process typically consists of an infinite loop that receives a request 
for service, processes it, receives die next request, and so on. 

Because all message- passing is synchronous, the main process typically cannot employ the Send() 
primitive, lest it block indefinitely. For this reason and others, servers implemented outside die kernel often 
employ additional processes, for example, to send messages for them, to service multiple input streams in a 
responsive fashion, or to manage multiple open "instances" (of objects) without complex multiplexing. These 
auxiliary processes arc generally called helpers. 
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Figure 3M: The V-System: A single workstation view. 
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31.1.2. Machine- relative Servers 

Machine-relative servers are servers, instances of which exist on every workstation running V. 

31.1.2.1. Kernel Server 

The kernel server is a pseudo-process embedded in the kernel that handles all requests to manage processes, 
as well as the requests to create and terminate teams. 

31.1.2.2. Device Server 

All hardware I/O devices attached to the workstation arc serviced by the device server, which is a pseudo- 
process embedded in the kernel. The device server supports the standard I/O and naming protocols 
discussed in Chapters 33 and 34, respectively. Consequently, it behaves like any other I/O server as far as 
applications are concerned. 

31 .1 .2.3. Team Server 

The team server is the manager of the physical host 13 It loads, executes, and monitors all teams other than 
the first. (Recall that a team usually corresponds to a program, although some programs consist of more than 
one team.) Requests to the team server ask it to load and start a team, to terminate one, or to print the 
directory of currently executing teams. 

The team server also provides the bulk of the remote execution and migration facilities. It implements the 
policies that determine whether to accept other workstations' programs for execution to begin with and 
whether to preempt them later on. It also implements the facilities needed to migrate programs between 
workstations. 

31 .1 .2.4. Exception Server 

The exception server is notified whenever a process incurs an exception. If another process has registered 
itself as the exception handler for the process that incurred the exception, the exception server simply 
forwards the exception to the registered handler. Otherwise, it prints a message on the screen (using the 
console device). The latter case docs not arise very often in practice, however, because the team server 
registers itself as the exception handler of last resort for almost all processes, 

31.1.2.5. Workstation Agents 

Workstation agents were discussed at length in Chapter 2. Here, we merely present the basic 
implementation of the VGTS as a canonical example of server structure. 

The VGTS is structured as one server process with three helper processes (sec Figure 31-2). There is one 
helper process to receive input from the mouse (through the device server), one to read from the keyboard, 
and a timer process to invoke periodic functions like redrawing the screen. The keyboard and mouse helper 
send requests to the device server, and block until input arrives. When they receive a reply, they then send 
the input to the main server process, and request more input from the device server. This is a typical use of 
helper processes for processing multiple input streams, simultaneously and in a responsive manner. 

Note: Although grouped with alt the other machine-relative servers, workstation agents arc distinguished by the fact that 
they need not exist at all. That is, if the workstation docs* not support any user I/O devices there is no need for it to support 
a workstation agent 



13 
In some documents it is also referred to as the program manager. 
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Figure 31-2: VGTS process structure. 



31 .1 .2.6. Executives and the Exec Server 

While the workstation agent provides the low-level I/O interface for the user, the executive provides the 
command processing interface. It corresponds to the Unix shell or the Tops-20 Kxcc, in that it is a user-level 
process providing command parsing and convenient access to system services. 'Hie basic operation of the 
executive is documented fully in Chapter 3. 

All instances of the executive on a workstation arc managed by the exec server. Its purpose is to allow 
sharing of code and data (such as aliases) among all executives. 

31 .1 .3. Global Servers 

A global server is distinguished by the fact that it is designed to service requests from any workstation, not 
just from processes running on the workstation on which it happens to be running. 
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31.1.3.1. Authentication Server 

The authentication server provides the basic mechanisms by which users log in to the V-Systcm and by 
which security is maintained, 

31 .1 .3.2. Storage Server 

Storage servers generally provide for long-term information storage. They typically run on workstations 
will large disks attached, or on Vax/UNIX systems. Each host may support at most one storage server. A 
"RAM disk" facility is also provided, in the form of the memory server. 

31 .1 .3.3. Internet Servers 

Internet servers provide for network communications using standard (internet protocols, as compared to 
the inter-kernel protocol implemented by the V kernel They are essentially protocol converters that allow 
applications that communicate by means of the V I/O protocol to communicate with hosts that can only (or 
prefer to) be reached by a protocol other than the inter-kernel protocol. 

31 .2. The System in Operation 

Having summarized the functions of each of the major servers in isolation, we now describe some of the 
ways in which these servers interact. The intent is not only to help the reader understand the basic structure 
of the system', but also to understand some basic techniques for multi-process structuring. 

31.2.1. System Initialization 

When a workstation is booted, its PROM loads a program that loads the V kernel and the first team. After the 
kernel has completed its internal initialization, it creates an initial team space and an initial bootstrap process 
on this team, and assigns the processor to this process. The bootstrap process starts all the servers necessary to 
run the sysrem on the workstation: the exception server, the team server, the exec server, and some version of 
a workstation agent All but the last arc always loaded together on the first team, and thus share a single 
address space; the workstation agent may or may not be loaded on the first team, at the discretion of the user. 
The advantage of placing it on its own team is that then it may be replaced dynamically using the newterm 
command. 

31 .2.2. Loading a Team 

Teams other than the first can be loaded from object code files using routines in the V C program library. 
These routines package an appropriate request to the team server and take care of matters such as initializing 
the team's data space as discussed in Section 18.4. The detailed message traffic involved is illustrated in 
Figure 31-3: In its request to the team server (edge 1), a client includes an open file descriptor specifying the 
file to be loaded. This descriptor references the storage server that manages the file (edge 2) and from which 
the file will be loaded. After receiving the request, the team server requests the kernel server to create a new 
team with initial process (edges 3 and 4). Like all processes, it is created in the awaiting reply state — waiting 
for a reply from its creator. In effect, the kernel simulates a Send( ) from the process to die team server 
(edge 5). The team server forwards this message, and its associated privileges (including access to the entire 
address space of the new team), to die client that originally asked for the team to be loaded (edge 6). At this 
point, the client (or the library routine it called) can initialize the team's environment variables and die like, 
and tiicn Reply( ) (edge 7), thus allowing the new team to begin execution — all as discussed in Section 
18.4. 
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Figure 31-3: Loading a team. 

31 .2.3. Team Termination and Exit Status 

Barring catastrophic failures, the _start routine loaded with every team will ensure that the team's owner 
is always notified of the termination of the team — by sending it an appropriate message. If the team 
terminated gracefully — by calling ex1 1( ) or returning from mal n( ) with a valid exit status — the owner 
will be able to ascertain the team's exit status. 
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31.2.4. Command Processing 

Prior to running an application, the executive must determine what program is to be run! It does so by 
parsing the command line returned in response to its request for line-edited input from the workstation agent 
The executive then opens the file that contains the program (edge 2 in Figure 31-3), and any other files as 
necessary to handle redirected I/O. Finally, it invokes the procedure discussed in Section 31.2.2 above. 

Unless the program is being run in the background, the executive waits for it to complete execution by 
waiting for a message from it 14 If the team terminates by calling ex1 1( ) or returning from ma1n( ), the 
executive will indeed receive a message from it containing the team's exit status. Otherwise, the team will 
have died abnormally, in which case the executive will awakened by the kernel and informed of that fact At 
this point it is ready to ask for the next command line. 

31 .2.5. Exception Handling 

As described above, the team server uses only the services of the kernel and a storage server. However, the 
team server is also the principal client of the exception server. Figure 31-4 illustrates the message flow 
involved: The team server creates the team to begin with (edges 1 and 2) as described above. It then registers 
itself as the exception handler for the team (edge 3). If a process on the team incurs an exception, the kernel 
simulates the effect of the offending process sending an exception message to the exception server (edge 4), 
which forwards the message to the team server (edge 5). The team server then uses its own facilities to load 
the V debugger (edge 6), and forwards the exception message to it (edge 7). 




4. 



C Exception 
Server 

Figure 31-4: Handling an exception. 
Upon receipt of the message, the debugger prints the exception data on the screen and registers itself as the 



14 
Programs running in the background have the team server as their owner. Then, if the executive that started them is deleted by the 

user, which usually results in the destruction of any program it owns, the background program will continue execution. 
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(new) exception handler for the offending team. It then handles user commands, one of which may cause the 
team to be "resumed", in which case the debugger simply replies to the original exception message, freeing 
the team to continue execution until it either gets another exception or terminates normally. The next 
exception, if any, will of course be handled by the debugger. 

Note: If a process other than the team server had registered interest in the offending process before it incurred an exception, 
the exception message would have been forwarded directly to the registered exception handler. The handler can then take 
any action it deems appropriate, including loading the debugger as discussed above. 

31.3. Summary 

One of the principles guiding the V-System design has been to place as many the usual operating system 
functions outside the kernel as efficiency permits. Moreover, functions have been partitioned as far as 
practical into separate servers. Consequently, the kernel and each server have been kept reasonably small and 
independent of each other, which has in turn simplified debugging, maintenance, and experimentation with 
new servers. 
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Message Codes and Format Conventions 

This chapter describes the standard message formats and codes used throughout the V-System. 

32.1 . Message Format Conventions 

System server protocols obey several system-wide cdnventions. Every request message contains a 16-bit 
request code indicating the service requested. Similarly, every reply message contains a 16-bit code indicating 
the successful completion of the request's execution or the reason that the request was not executed normally. 
A requesting process can assume that the request has been completely executed when the reply message is 
received with a successful reply code (although in cases such as disk write-behind this may not be strictly 
true). 

32.2. Byte-Ordering Considerations 

V may run on a mixture of Suns and VaxStations. The former contain Motorola 680x0 processors which 
use the first (lowest-addressed) byte of a 16-bit or 32-bit quantity to store the most significant byte of the 
quantity ("big-endian"), while the latter use VAX-architecture processors which store the least significant byte 
first ("little-endian"). When processes running on the two architectures exchange messages, some conversion 
must be done (if messages included floating-point or other highly architecture-specific data, considerably 
more conversion would be necessary; to date, however, only 16-bit and 32-bit integers have been required). 

The kernel, servers, includc-filcs and library routines have been altered to perform the appropriate 
conversion (byte-swapping) for all code in the V-Systcm distribution. However, anyone who implements a 
server or who uses message-passing that docs not fit die client-server model should be aware of how byte- 
swapping is done. 

The kernel always sends inter-kernel packets in its own byte order. A kernel which receives an IKC packet 
must determine the byte order of the packet and, if necessary, byte-swap the packet, including the message 
contained therein (sec IKXJ.ITTIE_ENDIAIH, DlfferentlKCByteOrder and SwapIKPacket in 
V1kc. h). Currently, the kernel swaps the message as though every message were eight longwords, and treats 
any segment as a stream of bytes (hence docs nothing to the segment). 

Any further swapping of the message must be done by a process. We have adopted the policy that a client 
sends messages and gets replies without regard to byte order. It is then the responsibility of the server to 
perform any necessary swapping of requests and replies. The server can always determine the byte order of 
the message's sender because it is encoded in the sender's logical host id (sec LITTLE_ENDIAN_HOST and 
DlfferentByteOrder in Venvlron.h)* The server must, of course, take account of swapping 
performed by the kernel. 

In many cases it is not actually necessary for the process to byte-swap messages at runtime; rather, the struct 
definition for the message can be #ifdcfcd for big- and little-endian architectures so that 8- and 16-bit fields 
automatically end up in the right place. The MicroVAX C compiler ^defines LITTLE_ENDIAN for this 
purpose; die 680x0 C compiler docs not. The definition of a Kernel request in Venvlron.h 
demonstrates the use of LITTLE_ENDIAN. 
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32.3. Standard System Request Codes 

Each system request is allocated a unique request code to be placed in the first word of the request message 
when requesting that service. The request codes obey the message format conventions imposed by the kernel, 
as described for Send ( ) in Chapter 27. r lTic manifest constant definitions for these request codes arc defined 
in the standard C include file Venvl ron . h. 

32.4. Standard System Reply Codes 

The reply code returned. in a message from a server is normally one of the following standard system 
replies: 

OK Operation successful. 

ABORTED An operation was aborted. For example, a network connection that has been aborted 

returns this code. 

AWOKEN Returned by the kernel server when a Delay request was terminated by a Wakeup. (It is 

not returned by the Delay library routine, however.) 

BAD_ADDRESS Request contains an invalid memory address. 

BAD_ARGS Request contains ficld(s) with illegal or inconsistent values. 

BAD.BLOCK.NO 

The block number specified in an I/O request docs not specify an existing block. If die file 
instance has attribute STREAM, the block number docs not specify the block which is 
sequentially next in reading or writing. 

BAD_BUFFER A buffer specified in the request lies (perhaps partially) outside the client's address space. 

BAD.BYTEJTOUNT 

The byte count is larger (or smaller) than that supported by the server. On a file instance 
without the MULTI.BLOCK attribute, this is returned if the number of bytes requested to 
read or write is greater than the block size. 

BAD.FORWARD 

BAD_FORWARD is returned by the kernel when a Send is unblocked due to die receiver 
issuing an invalid Forward kernel operation. 

BAD.PR0CESS.PR10R1TY 

The request specified an illegal value for a process priority. 

BAD_REPLY_SEGMENT 

If a process invokes Rep1yW1thSegment() with a segment to which it docs not have 
write access, the kernel sets the reply code of the message returned to the sender to 
BAD_REPLY_SEGMENT. 

BAD.STATE Request invalid at diis time. 

BUSY The server cannot satisfy the request at this time, probably because a single-user resource is 

already allocated to another client 

DEVICE.ERROR 

File or device-dependent error has occurred. 

DUPLICATEJMAME 

The request attempted to assign the same name to two different objects. 

DISCARD.REPLY 

This reply code is used with the Reply ( ) primitive when the process receiving a message 
docs not wish to reply. Reply messages containing this reply code arc never delivered. 
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END_OF_FtLE Attempt to read beyond file boundaries. 

HAS.SUBSTRUCRJRE 

Returned by the storage server when a client attempts to remove a file that has a son in the 
directory tree. ITie attempt fails. 

ILLEGAL.NAME 

Returned by a server that deems a name to be illegal- for example, the name might be too 
long. 

ILLEGAL.REQUEST 

Invalid request codei The request was probably sent to the wrong type of server, one 
which could not perform that function. 

INTERNAL_ERROR 

The server detected an inconsistency in its own state. This error code may indicate a bug in 
the server. 

INVALID.CONTEXTJD 

The request contained a context identifier (sec chapter 34) that was invalid. 

INVALID.FILEJD 

The request contained an invalid file instance identifier. 

INVALIDJvIODE 

The mode specified as part of a CREATE .INSTANCE request is not valid 

IO.BREAK Returned from interactive files when the user hi$ the BREAK (Ctrl-C) key. It currently 

isn't 

KERNEL.TIMEOUT 

A timeout occurred in the kernel when trying to send to a remote process. This error 
differs from NONEXISTENT_PROCESS in that the sending kernel did not receive a 
negative acknowledgement from the remote kernel, but for most purposes it can be 
handled in the same way. This error code is only generated by the kernel, but may be 
passed on by other, servers. 

MODE NOT SUPPORTED 

The mode specified as part of a CREATEJNSTANCE request is not supported by this 
server. 

MORE_RHPUKSAn operation request sent to a group was successful, and the client should use 
Ge tRep 1 y ( ) to check for additional replies from other group members. 

MULTI.MANAGER 

The requested operation is not supported on multi-manager objects. 

NO_GROUP_DESC 

Returned when the kernel runs out of group descriptors. 

NO_M KMOR Y ITie server was not able to obtain enough memory to satisfy the request 

NO_PDS 'Hie server was not able to create a process needed to satisfy the request 

NO.PERMISSION 

Some kind of restricted operation was attempted. 

NO_SERVER_RKSOURCES 

ITie server has (temporarily) inadequate resources to satisfy the request 

NOJTDS The server was not able to create a team needed to satisfy the request 

NOT_A_CONTEXT 
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The request asked the server to perform an operation that is only defined on contexts, but 
the specified object was not a context 

NOT.HERE The character-string name specified in the request docs not specify an object implementing 
by the receiving server, but may be defined by some other server. This reply code is never 
returned to a message sent to a process group unless the rcplicr knows that no member of 
the group implements the name. 

NONEXISTENT.PROCESS 

The request was sent or forwarded to a nonexistent process, or a nonexistent process was 
specified in the request This error code is only generated by the kernel, but may be passed 
on by other servers. 

NONEX1STENT..SESSION 

The request referred to a session (see chapter 43) which does not exist or to an object 
which is not a session. Obsolete.. 

NOT.AWAITINGREPLY 

The process specified in a request was not awaiting reply from the client 

NOT.FOUND The object named in the request was not found. 

NOT_READABLE 

Specified file instance docs not have the attribute READABLE which is required for the 
requested operation. 

NOTWRITEABLE 

Specified file instance docs not have the attribute WRITEABLE which is required for the 
requested operation. 

POWER_FAILURE 

Operation was unsuccessful due to a power failure. 

REQUEST.NOT.SUPPORTED 

The server recognizes the request but docs not support it 

RETRY Client should repeat request 

RETRYJJNICAST 

The request was sent to a group, but the responding server refuses to perform it in parallel 
with other members of die group. The client should retry the request this time as as a 
one-to-one Send( ), not a multicast 

SERVER.NOT.RESPONDING 

The server failed to receive a response from another server specified in the request 

TIMEOUT An attempt to satisfy the request failed because of a timeout Usually applied to network 

connections. 

The ErrorStMng() function will return a character string version of many of the system reply and 
request codes. The string form is much more informative than printing the codes in numeric form. 
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The V-System J/0 Protocol 



A standard input/output protocol is defined in V to provide transfer of data between processes in a uniform 
fashion. Using this protocol, a client process views and accesses data managed by a server process as a file. A 
file is a "view" of the data associated with an object or activity managed by a server. An object viewed as a 
file is a sequence of variable-size records or blocks. 

To operate on an object viewing it as a file, it is necessary to create an instance of that file. The protocol is 
object-based in the sense that it is defined in terms cf operations on a object, the file instance. File instance 
operations include: creating a file instance, querying a file instance, setting the file instance owner, reading, 
writing, and releasing file instances. There are also operations for setting a prompt string and break process 
associated with a file instance which arc restricted to interactive file instances. A server that supports this 
protocol is called an I/O server or file instance server. (The term "file server" might be more appropriate if it 
did not have a different established meaning in the research literature on distributed systems). 

A file instance is created by a server in response to a client request, which specifics the file, i.e. the object or 
data and the particular view and usage required. Conceptually, a file instance is an object which is created at 
the ume of the client's CREATEJNSTANCE request, and (possibly) initialized to contain the same data as 
an existing, permanent file. When the instance is released by the client, the data contained in the instance is 
atomically written back to the corresponding permanent file. For some servers (for example, the internetwork 
server), however, there is no permanent file corresponding to an instance, while for others (for example, the 
device server), there is effectively no distinction between the instance and the permanent file -changes in die 
instance arc immediately reflected in the underlying file or I/O device. The current implementation of some 
storage servers (e.g., the V Unix server) also causes changes in an instance to be immediately reflected in the 
underlying file. 

A file instance is uniquely identified by the server process identifier and the instance identifier returned by 
the CREATEJNSTANCE request. The creating process is made the owner of the file instance. ITic lifetime 
of the file instance and the validity of the instance identifier docs not exceed that of the owner of the file 
instance. Hie owner of a file instance can be changed by the SETJNSTANCE_OWNER request 

The reply message to a CREATEJNSTANCE or QUERYJNSTANCE request specifics the server file 
instance identifier, block length in bytes, file type, last block (written) in the file instance, number of bytes in 
the last block, and the next block to read 

The file type indicates the operations that may be performed on the file instance as well as the semantics of 
these operations. These types arc defined in the include file <Vio.h>; file types arc specified as some 
combination of the following attributes. 

READABLE READJNS TANCE operations arc allowed on the file instance. 

WRITEABLE WRITEJNS TANCE operations arc allowed on the file instance. 

APPEND.ONLY WRITEJNS TANCE operations arc only effective to bytes in the file instance beyond the 
last byte associated with the instance at the time it was created. 

STREAM All reading and writing is strictly sequential. 'The first READJNSTANCE operation must 

specify the block number returned as nextbhek in the reply to the CREATEJNSTANCE 
request 'lliis next block number to read is incremented after each READ* INSTANCE 
operation. Its current value is returned by a QUERYJNSTANCE. A scrvcr~that uses the 
Rep1yW1thSegment() kernel operation to return the data requested in a 
READJNSTANCE must store the last block read and allow it to be read again, to provide 
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duplicate suppression on requests. 

WRITE INSTANCE operations on STREAMS always write to lastblock+1, where 
lasiblock is a value- returned by CREATEJNSTANCE or QUERYJNSTANCE. This 
block number is incremented after every write operation. The block number specified in 
the request message is ignored. 

A file instance without the STREAM attribute stores its associated data for non-scqucntial 
("random") access. That is, on a non-stream file, for any n, block n may be read or written 
at any time, and reading block n will return the same data as was last written to block n. 

Since each file models a single sequence of data blocks, objects which provide bidirectional 
communication, such as serial lines or network connections, are most appropriately 
modeled as a pair of file instances, one a READABLE STREAM, the other a 
WR1TEABLE STREAM. Some servers may allow both instances to be created by a single 
CREATEJNSTANCE request. 15 

FIXED.LENGTH 

The file instance is fixed in length. The length is specified by the last block and last byte 
returned from a create or query instance request Otherwise the file instance grows to 
accommodate the data written or else the length of the file instance is not known (as in the 
case of terminal input). 

VARIABLEJBLOCK 

Blocks shorter than the full block size may be returned in response to read operations other 
than due to end-of-file or other exception conditions. For example, input frames from a 
communication line may differ in length under normal conditions. 

With a file instance that is VARIABLE_BLOCK, WRITEABLE, and not STREAM, 
blocks that arc written with less than a full block size number of bytes return exactly the 
amount written when read subsequently. 

MULTIJJLOCK Read and write operations arc allowed that specify a number of bytes larger than the block 
size. 

INTERACTIVE The file instance is a text linc-oricntcd input stream on which a prompt can be sot using the 
SET.PROMPT request and a break process can be defined using the 
SFrjiREAK_PROCHSS request. It also has the connotation of supplying interactively 
(human) generated input 

Not all of the possible combinations of attributes yield a useful file type. The file instance types supported 
by each server arc documented with each server. 

A client must specify a mode of usage for the file instance when creating it. The mode is one of FREAD, 
FCRKATE, FMOD1FY and FAPPEND. The modes of usage have the following semantics. 

FREAD No write operations arc to be performed, only reads. 

FCREATE Any data previously associated with the described file is to be ignored and a new file 

instance is to be created. Write operations arc permitted; read operations arc also 
permitted if the file instance has type attribute READABLE. 

FAPPEND Data previously associated with the described file remain unchanged. Write operations are 



A Tew existing servers bend this rule by assigning the same instance id to the input and output streams, even though block number n 
of the input stream is unrelated to block number n or the output stream. Strictly speaking, this behavior is in violation of the protocol, 
and wc plan to change these servers eventually. A single STRF.AM that is both RRADAIll-li and WRITFABI.F would have to return 
the data written to block n if block n is later read back. 'IliLs type or Hie might be used to model a Unix-like pipe, but in Tact, the 
V-Systcm pipe server (sec chapter 41) takes a different approach, creating a separate instance for each end of the pipe, with the 
connection between them invisible to the protocol. 
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permitted only to append data to the existing data. 

FMODIFY Existing data is to be modified and possibly appended to. Both read and write operations 

are required. This is only supported on file instances that are not STREAM. 

A server creates a file instance of a suitable type for the specified usage mode if it can. For example, the 
storage server provides file instances with type attributes READABLE, FIXED_LENGTH and 
MULTLBLOCK in' response to a CREATEJNSTANCE request specifying FREAD usage mode. 

One of three modifiers may be used on the mode field of a CREATEJNSTANCE request 
FDIRECTORY Indicates that the given name specifies a context directory. See section 34.10. 

FEXECUTE Specifies that the given file is to be executed as a program on the storage server machine. 
The mode must be FREAD or FCREATE Respectively, one or two file instances are 
returned, which allow reading from the program's standard output, and optionally (in 
FCREATE mode) writing into its standard input When two instances are created, the 
fileid of die second (readable) file instance is obtained by adding 1 to the filcid of the 
writeable instance (which is returned in the reply message). This mode modifier need not 
be supported by all storage servers. 

The following subsections give the format of the request message and the format of the reply, plus a 
description of the semantics for each operation in the protocol. These message formats arc defined in the C 
include file <Vioprotocol.h>. 



33.1 . CREATE INSTANCE 



rcquestcode CREATEJNSTANCE 

filcnamcindcx The index of the first byte in the filename to use in the name mapping. 

type Type of file to create an instance of, for servers that do not support character-string 

naming. This is used, for example, to specify the protocol to the internet server. 

filcmodc Desired usage mode Indicating FREAD, FCREATE, FAPPKND or FMODIFY, plus 

optionally FDIRECTORY or FEXECUTE. 

unspecified Server-dependent information specifying the file to be created, for servers that do not 

support character-string naming. 

contextid Specifics the context within the server in which the filename is to be interpreted. (See 

section 34.3.) 

filename Pointer to a byte array containing the symbolic name of the server or file. 

filcnamelcn Number of bytes in filename, not including the terminating null byte. ■ 



rcplycodc Standard system reply. If the reply code is not OK, the file instance was not created and 

the remainder of the reply is not defined. 

filcid File instance identifier, litis is the number used in subsequent operations on the file. 

filcserver Process identifier of the server managing this file. This is not necessarily the same as the id 

to which the request was sent 



* 6 AII newly written servers that provide the CRUA TI;JNSTANCI' operation should support character string naming and should not 
use the type or unspecified fields of the CrcalclnstanccRcqucst 
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blocksize Maximum size in bytes of a block. 

filetype Type attributes of the file instance as described at the beginning of this section. 

filelastblock Index of the last block in the file or of the last block written to the file instance if it is a 
STREAM file. Indexing is O-origin. 

filelastbytcs Number of bytes in the last block. For file instances which are not WRITEABLE and not 

FIXED J-ENGTH, this field and die filelastblock field should return the maximum 
unsigned integer. 

filencxtblock Number of the next block that can be read if this file is a READABLE STREAM. 



The filename field of a CREATEJNSTANCE request specifies the type and properties of the instance to 
be created, perhaps by naming some existing permanent object The request is issued either directly to the 
server or sent to a group including the server, as described in section 34. 

The field and fileserver uniquely identify the file instance created. The file instance exists until released or 
until the requesting process ceases to exist 



33.2. QUERY INSTANCE 



requestcode QUERY.INSTANCE - ? 

fileid File instance identifier. 



replycode A standard system reply.. If the reply code is not OK, the file instance was not queried and 

the remainder of die reply is not defined. 

fileid File instance identifier, same as the request for compatibility with the reply to the 

CREATEJNSTANCE request 

fileserver Server process identifier. • ll 

blocksize The maximum size in bytes of a block. 

filetype Type attributes of the file instance as described at the beginning of the section. 

filelastblock Index of the last block in the file or the last block written to the file instance if it is a 

STREAM file. Indexing is O-origin. 

filclastby tes The number of by tes in the last block. 

filencxtblock Number of the next block that can be read if the file is a READABLE STREAM. 



In response to a QUERY_ INSTANCE request message, the server queries the file instance specified by 
fileid for the parameters supplied in ihc reply- message. The reply message has the same format and semantics 
as the reply to a CREA TEJNSTANCE request except for Uic reply code. For example, a reply code of 
NOT_FOUNI) to a CREATEJNSTANCE request indicates that the file specified docs not exist, while a 
reply code of INVAL1D_F1LE_ID to a QUERYJNSTANCE request indicates the file instance docs not 
exist 



33.3. CREATE DUPLEX INSTANCE 



requestcode CREATEJ)UPLEXJNSTANCE 
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filcid 
mode 



File instance identifier. 
Desired usage mode. 



replycode A standard system reply. If the reply code is not OK, the file instance was not created and 

the remainder of the reply is not defined. 

fileid File instance identifier, same as the request for compatibility with die reply to the 

CREATEJNSTANCE request. 

fileserver Server process identifier. 

blocksize The maximum size in bytes of a block. 

filetype Type attributes of the file instance as described at the beginning of the section. 

filelastblock Index of the last block in the file or the last block written to the file instance if it is a 

STREAM file. Indexing is 0-origin. 

filelastbytes The number of bytes in the last block. 

filenextblock Number of the next block that can be read if the file is a READABLE STREAM. 



In response to a CREATE JXJPLEXJNSTANCE request message, the server creates (or causes to be 
created) the "other side" of a duplex file (such as a bi-directional network connection, or a terminal). The 
reply message has the same format and semantics as the reply to a CREATEJNSTANCE request except for 
the reply code. For example, a reply code of NOT_FOUND to a CREATEJNSTANCE request indicates 
that the file specified does not exist, while a reply code of INVALID_FILEJD to a 
CREATE.DUPLEX JNSTANCE request indicates the file instance docs not exist 



33.4. RELEASE INSTANCE 



rcquestcodc RELEASEJNSTANCE 

filcid File instance identifier 

rclcascmodc Server-dependent action to perform when releasing the instance. This field is set to zero 
on a normal close. 



replycode 



A standard system reply code. 



In response to a RELKASRJNSTANCE request, the server invalidates the instance identifier, reclaims 
server resources dedicated to the instance and possibly performs some scrvcr-dcpcndcnt function with the file 
instance data. A releascnuxle of indicates normal completion of the use of the file instance. For example, in 
the case of the printer server, the file instance data is printed. In the case of the storage server, the data 
atomically replaces the previous version of the stored file data. A non-zero release mode causes die data to be 
discarded. 

A server may release a file instance with a non-zero release mode if it detects that the process that created 
the instance no longer exists. A server should maximize the time before reusing a file instance identifier. 
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33.5. READ INSTANCE 



requestcode 

filcid 

block number 

buffcrptr 

bytecount 



READJNSTANCE 

File instance identifier 

Index of the block in the file from which the read is to begin. 

Address of the data buffer in which the data is to be moved if more than 
IO_MSG_BUFFER bytes are read. That is, IO_MSG_BUFFER is the maximum number 
of data bytes that fit in the message. 

Number of bytes to be read. 



replycode 

filcid 

shortbuffer 

bytecount 



Standard system reply code. 

Same as in request 

10 MSG BUFFER bytes containing the data bytes read if less than or equal to 
ICL MSGlBUFFER bytes. 

Number of bytes read. 



In response to a READJNSTANCE request, the server transfers up to bytecount bytes from the file 
instance starting at the block numbered blocknumber. If the number of bytes read is less than the number 
requested, the reply code indicates the reason. If the file instance has the type attribute VARIABLE_BLOCK 
and the block being read was not the full block size specified for the file instance, this case is not an error, and 
the reply may bo OK, or END_OF_FILE if the last block was read. Servers should set the byte count to zero 
on error conditions. 

If the number of bytes read is less than or equal to IO_MSG_BUFFER, the data read is contained in the 
reply message starting at shortbuffer. If it is greater than IO_MSG_BUFFER, the data read is transferred into 
the space of the requesting process starting at the address bufferptr. 

If the file instance has the type attribute STREAM, the block number specified must be the next block to 
read for this instance, which is incremented after the read. Reads always start at die beginning of the 
specified block. I"hc values of bytes read that were not explicitly written arc undefined. '11k number of bytes 
requested must be less than or equal to the block size unless the file instance has the type attribute 
MULTLBLOCK. 



33.6. WRITE INSTANCE 



requestcode WRITF. INSTANCE, or WRITESHORTJNSTANCE if bytecount is less than or equal to 

IO_MSG_BUFFER. 

filcid File instance identifier. 

blocknumber Index of the block in the file instance at which the write is to begin. 

shortburTcr Data bytes to be written if less than or equal to IO_MSG_BUFFER. 

buffcrptr Address of the data buffer if no more than IO_MSG_BUFFER bytes arc being written. 

Otherwise, this field may be overwritten by the data bytes. 

bytecount Number of bytes to be written. 
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replycodc Standard system reply code, 

bytccount Number of bytes written. 



In response to a WRITE JNSTANCE or WRITES HORTJNSTANCE request, the server transfers up to 
bytecount bytes to the file instance starting at the block numbered blocknumber. If the number of bytes 
written is less than the number requested, the reply code indicates the reason. As with READJNSTANCE, 
servers should set the byte count to zero on error conditions. 

If the number of bytes to write is less than or equal to IO_MSG_BUFFER, the data is assumed to be 
contained in the request message starting at shortbuffer. If it is greater than IOJ4SG_BUFFER, the data is 
transferred from the space of the requesting process starting at the address bufferptr. Writes always start at the 
beginning of the specified block. Note that the separate request code WRITESHORTJNSTANCE is used 
when the data is contained in the message only to be consistent with the kernel message format conventions. 
There is no READSHORTJNSTANCE needed because the data is passed back in the reply. That is, 
WRITEJNSTANCE specifics that segment access is being passed while WRITESHORTJNSTANCE 
specifies no segment access. 

If the file instance has type attribute STREAM, the block number written is one greater than the last block 
in this file instance, regardless of the block number specified. The number of bytes to write must be less than 
or equal to the block size unless the file instance has the type attribute MULTI.BLOCK. 

33.7. SET INSTANCE OWNER 



requestcode SETJNSTANCE_OWNER 

fileid File instance identifier 

instanceowner Process identifier of new file instance owner. 



replycode Standard system reply code. 



In response to a SETJNSTANCEJDWNFR request, the server sets the file instance owner process to that 
specified by instanceowner. 'ITic requesting process must be the current owner of the file instance. Hie initial 
owner of a file instance is the process that created the instance. 

33.8. SET BREAK PROCESS 



requestcode SET_BREAK_PROCESS 

fileid File instance identifier 

breakproccss Process to be "broken" when next break generated on this file instance. 



replycode Standard system reply code. 



In response to a SETJJREAK_.PROCF.SS request, the server sets the break process associated with the file 
instance to the process specified by breakproccss. When a break is generated on this file (the IOJJREAK 
reply returned to any outstanding read operations), the server issues a Destroy Process kernel operation on the 
specified process. 



V Servers 12 March 1986 



33-8 



The V-System I/O Protocol 



This request is only supported on file instances with type attribute INTERACTIVE 



33.9. SET PROMPT 



requestcode SET_PROMPT 

fileid File instance identifier 

promptstring Prompt string, which must be less than IO_MSG_BUFFER bytes long. 



replycode 



Standard system reply code. 



In response to a SET_PROMFT request, the server sets the prompt string output previous to every read 
operation to that specified. This request is only supported on file instances with type attribute 
INTERACTIVE 



33.10. QUERY FILE and NQUERY FILE 



requestcode 

fileid 

unspecified 



QUERYJTLE 

File instance identifier 

Server-specific. 



requestcode NQUERY.FILE 

namcindcx The index of the first byte in the file name to use in the name mapping. 

unspecified Server-specific 

namccontextid Context in which the name is to be interpreted. 

nameptr Pointer to a memory segment containing the file name. 

namclcngth Length of the segment in bytes. 



replycode Standard system reply code, 

unspecified Server dependent information. 



In response to a QUKRY_FILE or NQUERY.FII.E request, the server returns server specific information 
about die file or file instance. For example, the VG IS returns the "cooking" bits, and the internet server 
returns connection information. A QUKRY_FILE request specifics the file using an instance identifier, while 
a NQUERY.FILE request uses a character-string name. Itoth types of request return the same information. 



33.1 1 . MODIFY FILE and NMODIFY FILE 



requestcode 
fileid 



MODIFY.FILE 
File instance identifier 
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unspecified 



Server-dependent information. 



requestcode NMODIFY_FILE 

nameindex The index of the first byte in the file name to use in the name mapping. 

unspecified Server-dependent information. 

namccontcxtid Context in which the name is to be interpreted. 

nameptr Pointer to a memory segment containing the file name. 

namelcngth Length of the segment in bytes. 



replycode 



Standard system reply code. 



The MODIFY.FILE and NMODIFY_FILE requests are supported by some servers to modify some 
attributes of the file or file instance. For example, die device server uses MODIFY_FILE to change the data 
rate on RS-232 serial interfaces. 

A MODIFY_FILE request specifics which file is to be modified by passing an instance identifier, white an 
NMODIFY.fTlE request passes a character string name. 
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The V-System Naming Protocol 



A number of V-System services use character string names to specify the objects to be operated on, and 
many standard message types include space for such a name. Examples include the CREATEJNSTANCE 
request and several other requests described above as part of the I/O Protocol. 

Name mapping in the V-System is decentralized, being performed by a collection of cooperating server 
processes rather than a single, monolithic "name server." The V-System Naming Protocol consists of a 
uniform format for request messages that contain high-level names, a method for locating the server that 
implements any given named object, and a small set of request types that must be handled specially by any 
server that implements the protocol. 

In this chapter, we describe the naming protocol in detail and give implementation hints for servers that use 
it Refer to Chapter 25 for a description of the naming library routines available to client programs. 

34.1. Overview 

•Conceptually, the V-System naming facility is a system-wide global directory providing reference by high- 
level (character-string) name to objects implemented by multiple object managers (servers). The global 
directory contains a (name, objcct)-tuplc for each binding of global name to object Each client may also 
have its own directory of bindings from local names (or aliases) to global names. The naming facility provides 
operations for 

• Binding names to objects 

• Removing name bindings 

• Name mapping: finding objects bound to a given name 

• Inverse name mapping: finding the name bound to a given object 

In the decentralized V naming facility, the global directory is distributed across die object managers such 
diat each object manager stores and maintains that portion of the directory corresponding to the objects it 
implements. Each client program maintains a cache of bindings from name to object manager, as illustrated 
in Figure 34-1. When a client invokes an operation using a high-level object name, die client checks its cache 
for an entry that maps die name to an object manager. If a cache entry for the name is found (as is the case 
with name! in Figure 34-1), the operation and name arc then sent to the object manager indicated by' the 
cache entry. Otherwise, a query is multicast to the object managers to determine the correct object manager 
for the named object (as is the case for name! in Figure 34-1). If an object manager responds, a cache entry is 
created and die processing of the request proceeds as before, with the operation being sent to the responding 
object manager. Otherwise, the specified object name is assumed to be invalid and an error indication is 
returned to the client 

Inverse name mapping is simply a lookup in the global directory using an object's low-level identifier (for 
example, its instance identifier) in place of its high-level name. We assume that the low-level identifier 
provides enough information to determine which manager implements the object in question, and hence 
which manager stores the portion of the global directory containing its name. 'Hie same (absolute) global 



17 Notc that high-level names arc bound directly to objects, not to low-level names (such as globally unique numeric identifiers). Our 
design views high-level names as the only permanent, globally unique identifiers for objects. 
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Figure 34-1: Decentralized Global Directory 

name is returned for a given object even if the client originally accessed the object using a local name, alias, 
etc. Low level identifiers arc not standardized across all object types, so the inverse name mapping operators 
provided arc type-specific. 

34.2. Character String Names 

Syntactically, a character string name (CSname) is a sequence of zero or more bytes, of a specified length or 
else terminated by a null byte. Operationally, a character string name is a byte string as above that is used to 
specify an object relative to a server that can interpret the name. There is no universal limit on the length of 
character string names. Two CSnamcs arc equal if and only if they arc byte-wise identical and equal in length 
(where a null in the name takes precedence over the length specification). 

Although CSnamcs may contain arbitrary bytes, they arc generally specified or chosen by the client (as 
opposed to the server) and arc usually human-readable ASCII strings. 

The term character siring name handling server (CSNH server) refers to any server that performs character 
string name mapping, regardless of what else it docs. The term CSname request describes any request 
containing a character string name that must be mapped in order to perform the requested operation. 

34.3. Contexts and Context Ids 

The V-Systcm name space is hierarchically structured, and we refer to each internal node of the naming 
hierarchy as a context Names arc pathnames in that they describe a path through the hierarchy, beginning at 
(i.e., relative to) some specific context. Absolute names arc those lhat begin at the root context. 

The global directory is divided among object managers using a technique we call vertical partitioning. Each 
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object manager implements a tree of contexts starting at the root of the complete name hierarchy, thus storing 
the absolute names of the objects it implements. Some contexts (the root in particular) are implemented by 
multiple object managers. Such multi-manager contexts arc partitioned across the managers that participate 
in their implementation. Each participating manager stores only that subset of the context needed to name 
objects it manages. 

A context can be referenced by its absolute name, or by its context identifier, a compact low-level identifier 
that is effectively a pointer into the name space, providing direct, efficient access to the object managers) 
implementing the context. Referencing an object using a context identifier plus relative name allows the 
name lookup to start at the identified context rather than from the global root, thereby reducing the need for 

multicast and reducing the length of the name that must be looked up by the object managers. 

• 

In V, a context identifier is structured as a (manager-id, specific-context- id) pair, where the manager-id is a 
process identifier or process group identifier specifying the object managers) that implement the context, and 
the specific-context-id is mapped by the identified managers) to one of the contexts they implement The 
standard system header file <Venviron.h> defines the types Processld, Contextld (corresponding to 
specific-context-id), and ContextPal r, for these identifiers. 

When a context is renamed, its old context identifier becomes invalid and another is assigned. Thus, in 
effect, a context identifier is bound to a context name, not to the context object itself. 

Context identifiers are considered hints. That is, a context identifier is allowed to become invalid even if 
the corresponding character-string name is still bound to the same context For example, if a V object 
manager crashes and is restarted under a different process identifier, all its old context identifiers become 
invalid (since they contain die manager's process identifier as a subficld), even if all the objects it manages are 
recovered. 

34.4. Prefix Caching 

The client naming library maintains a prefix cache mapping from name prefixes to context identifiers. 
Before sending off any CSnamc request, the NameSend( ) library routine finds the longest name prefix that 
can be matched in the cache, (if the matched prefix maps to a multi-manager context, NameSend( ) issues a 
QUKRY_NAMK request (sec below) to obtain a longer prefix.) The matched prefix is then stripped off, and 
the resulting relative name is sent of? together with the context identifier to which the prefix mapped. If the 
request fails because the stored context identifier was invalid, NameSend() removes the offending cache 
entry and retries the request, continuing until the request succeeds or die name is known to be invalid. 

'Hie naming library also caches the context identifier of each client process's current context ("working 
directory"). 'ITie context's absolute name is also stored, allowing NameSend() to recover if its context 
identifier becomes invalid. 

34.5. Static Context Identifiers 

Static context identifiers arc defined for a few of the most commonly used multi-manager contexts. For 
each identifier, (he spccific-contcxt-id portion is defined in <Vnaming.h> and the manager-id portion is 
defined in <Vgroupids.h>. Static specific context ids arc small non-negative integers, less than the manifest 
consumtMAX.WBLX.KNOWN.CONTEX'l'S. 

In principle these identifiers need only be known to servers. To improve performance, however, several of 
the identifiers and corresponding name prefixes arc preloaded into client caches by the Pr1meCache( ) 
library routine. 

The following static (or well-known) context identifiers arc defined at this writing. 

(VCSNH - S1^RVKR_GROUP,GI.OBAIJ<OOT_CONTEX'0 
Corresponds to the CSnamc "[". 
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(VrEAM.SERVER.GROUP,TEAM.SERVER.CONTEXT) 
Corresponds to the CSnamc "[teamj". 

(VSTORAGE.SERVER.GROUP.STORAGE.SERVER.CONTEXT) 
Corresponds to the CSname "[storage]". 

(VTIMER.SERVER.GROUP.TIME.SERVER.CONTEXT) 
Currently not used for naming. 

(VAUTH.SERVERJ3ROUP, AUTH_SERVER_CONTEXT) 
Currently not used for naming. 

(VEXCEPTION.SERVER.GROUP,EXCEPnON_SERVER.CONTEXT) 
Currently unused. 

(VDEVICE.SERVERJ3ROUP, DEVICE_SERVER_CONTEXT) 
Currently unused. 

(VINTERNE'r.SERVER.GROUP.INTERNET.SERVER.CONTEXT) 
Currently unused. 

(VPRlNT_SERVER_GROUP, PRINT.SERVER.CONTEXT) 
Currently unused. 

(VVGT_SERVER_GROUP, VGT_SERVER_CONTEXT) 
Currently unused. 

(VPIPE_SERVER_GROUP, PIPE_SERVER_CONTEXT) 
Currently unused. 

(VEXEC_SERVER_GROUP,EXEC_SERVER_CONTEXT) 
Currently unused. 

(VTEST_SERVER_GROUP, TEST.SERVER.CONTEXT) 
Reserved. 

DEFAULT_CONTEXT 

Conventionally used for the local root context by many servers that implement a single tree 
of single-manager contexts. The name is an anachronism, left over from a previous version 
of the naming protocol. 

(VSTORAGILSHRVi:R_GROUP,PUnLIC_CONTEXD 

Holds publically-availablc V programs on storage servers. Corresponds to the CSname 
fsysj. 

34.6. Generic Names and Group Names 

A group name is a name that refers to a group (i.e., set) of objects, which need not all be implemented by the 
same server. A generic name refers to one member selected from such a group according to a rule associated 
with the name. The simplest (and most commonly used) rule is to select one member arbitrarily. 

The naming protocol supports generic and group naming by permitting more than one server to respond to 
a CSnamc request In general, the client issuing the name request determines whether the CSnamc is to be 
interpreted as a group name or generic name by receiving and processing all the responses (group name), or 
only the first (generic name with arbitrary selection). Selecting the first response has the pleasant side effect 
of favoring the most lightly-loaded server. 

Servers can also define generic or group names for contexts. In this case the servers determine whether the 
name can be used as a group name, or only as a generic name. Issuing a GetContextld request on a group 
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name for a set of contexts must return a ContextPalr that refers to all the contexts. 18 Subsequent name 
lookups that find the given prefix in the cache and substitute the returned context identifier will then 
correctly refer to all members of the set In contrast, each response to a GetContextld on a generic name 
for the same set of contexts may return an identifier for just one server's members) of the set Subsequent 
name lookups that find this prefix in the cache will then map it to the identifier that was returned in the first 
response. 

34.7. Name Request Format 

All V-System request messages that contain CSnames are built on a common skeleton, defined as the 
NameRequest structure in the standard header file <Vnaming.h>. 



rcquestcode Any valid request code that grants read access to a segment 

namcindex The byte offset of the name, within the segment specified by the last two long words of the 
message. 

unspecified Request-specific information. 

namecontexud A 32-bit identifier for die context in which this name is to be interpreted. 

nameptr Pointer to the segment containing the symbolic name. 

namelength Length of the segment containing the name. 



The reply is not specified by this protocol because it is generally dependent on the operation requested. 

The name need not be first in the segment but is considered to start at the byte offset specified by 
nameindex. If the name is not last in the segment it must be terminated by a null. 

The CSname request format includes only the spccific-context-id field of the ContextPalr for the 
context in which the name is to be interpreted, lire manager-id portion is implicitly specified by sending the 
request to the appropriate manager or group. 

34.8. Name Lookup Algorithm 

A server receiving a NameRequest performs the following algorithm to look up the name. 

l.Sct CurrentNode to the context specified by the namccontcxtid. If the context identifier is not 
recognized, fail with status IN VALID.CONTEXTJD. Go to step 4. 

2. While the name still has unmapped components, do 

• Attempt to map the next component of the name, relative to CurrentNode. 

o If the name component is not defined locally, but CurrentNode is a multi-manager 
context fail with stilus NOTJ IKUK. Go to step 4. 

o If die name component is not defined, and CurrentNode is not a multi-manager context 
fail with status NOT.FOUND. (We know the name cannot be defined by any other server.) 
Go to step 4. 

o If the name component is an upward reference (".."), and the context C to which it refers is a 
multi-manager context implemented by a different (larger) group than CurrentNode, 



18 Mulli-managcr contexts follow this rule, with the context name viewed as a group name for the set of partitions held by the 
participating servers. 
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advance nameindex to the next component following the upward reference, set 
namecontextid to C . c 1 d, and Fo rwa r d the request to C . p 1 d. Done. 

o Otherwise, the name component is defined. Set CurrentNode to the object it maps to and 
repeat 

3. The entire name has been mapped, and CurrentNode is the named object Done. 

4. Fail. 

• If the failure status was NOT.FOUND, and the request is of a type that permits automatic 
creation of an object in this case (for example, CREATEJNSTANCE in FCREATE mode on a 
file storage server), the object may be created at this point Its name will be the remaining 
unmapped portion of the given name, defined relative to the context CurrentNode. 

• If the request was multicast and the failure status was other than NOT.FOUND, do not reply 
(that is, invoke Reply () with rcplycode DISCARD.REPLY), since another server in the 
multicast group may have succeeded in processing it 

• Otherwise, the request was unicast Reply with the failure status. 

34.9. Standard CSNH Server Requests 

There are several standard CSNH requests that must be implemented by all CSNH servers, plus a few 
optional ones. All of the request and reply formats described below are subsets of the ContcxtRequest 
structure defined in the standard system header file <Vnaming.h>. 

34.9.1. QUERY NAME 



requcstcode QUERY.NAME 

nameindex The byte offset of the name relative to nameptr. 

namecontextid Context in which to interpret the given name, 

nameptr Pointer to the segment containing the symbolic name, 

namclcngth Length of the segment containing the name. 



rcplycode Standard system reply code. 

nameindex Advanced to indicate the context prefix recognized by the responding server. 

context A Con textPal r for the recognized context prefix. 



Query a name to get information that can be cached, typically to avoid multicast when mapping the name in 
ihc future. Implementation required of all CSNH servers. 

The query returns the shortest prefix of the given name that specifics a single-manager context together 
with a context identifier for that context If no prefix of the name specifics a valid single-manager context 
but the entire name specifics a valid multi-manager context the entire name is returned together with a 
context identifier for that context Otherwise, the query fails. A failing query returns K.ERNKL_T1ME0UT 
if multicast or a more specific error code if unicast (Multicast is the normal case.) 

A server receiving this request performs a variant of the general name-mapping algorithm, as follows. 

1. Set CurrentNode to die context specified by the namecontextid. If the context identifier is not 
recognized, fail with status IN VALID.CONTKX TJD. Go to step 4. 
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2. While Cur rentNode is a multi-manager context participated in by this server, do 

• Attempt to map the next component of the name, relative to Cur rentNode. 
o If the name has ho more components, go to step 3. 

o If the name component is not defined locally, fail with status NOT_HERE. Go to step 4. 
o If the name component is defined, set Cur rentNode to the object it maps to and repeat 19 

3. Succeed. In the reply, set namcindex to point to to the first component of the name that was not 
mapped, or if the entire name was mappei to just beyond the last character of the name (i.c., to the 
terminating null byte if there is one). Set context to the context identifier of Cur rentNode. Done. 

4. Fail. If the request was multicast, do not reply (that is, invoke Reply() with rcplycode 
DISCARD_REPLY), since another server in the multicast group may have succeeded in processing it 
If the request was unicast reply with the failure status. 

34.9.2. GET ABSOLUTE NAME 



rcqucstcodc GET_ABSOLUTE_NAME 

namcindex The byte offset of the name relative to nameptr. 

namecontcxtid Context in which to interpret the given name. 

nameptr Pointer to a buffer containing a symbolic name, and in which the absolute name is to be 

returned. 

namclength Size of the buffer. 

rcplycode Standard system reply code. 

context If the given name specified an existing context, a Con textPal r identifying it is returned 

in this field. 

nameptr The value provided is returned unchanged. 

namclength Length of the returned name. 



Returns an absolute CSname for the object whose (relative) CSnamc is given. The returned name 
overwrites the given name. If the name was not bound to a context contexLpid is set to in the reply. 
Implementation required of all CSNH servers. 

A server receiving this request performs a slight variant of the general name-lookup algorithm. The named 
object need not exist as long as it is clear what its absolute name would be if it were created. If the lookup 
fails with status NOT.FOUND, but it would be possible to create an object with the given name, the server 
constructs an absolute name by appending the undefined name suffix to the absolute name for the last 
Cur rentNode reached. 

34.9.3. GET CONTEXT ID 



rcqucstcodc GEX_CONTEXTJD 

namcindex The byte offset of the name, within the segment specified by the last two long words of the 



19 
Exception: upward references arc handled as described in section 34.8 
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message, 
namecontcxtid Context in which to interpret the given name, 
nameptr Pointer to the segment containing the symbolic name, 

namelcngth Length of the segment containing the name. 



replycode Standard system reply code. 

context A Context Pa 1 r identifying the named context 



Given a CSname that names a context, this request returns a (serverpid, contcxtid) pair that identifies the 
same context Implementation required of all CSNH servers. 

34.9.4. GET CONTEXT NAME 



requcstcode GET.CONTEXT.NAME 

context The ContextPal r for which a name is to be found, 

nameptr Pointer to a buffer in which the name is to be returned. . 

namelcngth Size of the buffer. 



replycode Standard system reply code. 

nameptr The value provided is returned unchanged. 

namelcngth Length of the returned name. 



Inverse name-mapping for context identifiers. Provides a subset of the functionality of 
GET_ABSOLU TBJMAMK. Implementation recommended for all CSNH servers. 

Returns an absolute CSname for the context corresponding to the specified context identifier, if the context 
identifier is valid and known to die server receiving the request. This request should be sent to the process or 
group identified by the pid component of the ContextPal r. 

34.9.5. GET FILE NAME 



requcstcode GET_FILE_NAME 

instanccid A file instance id for the file whose name is desired, 

nameptr Pointer to a buffer in which the name is to be returned, 

namelcngth Size of the buffer. 



replycode Standard system reply code. 

nameptr The value provided is returned unchanged. 

namelcngth Length of the returned name. 



Inverse name-mapping for instance identifiers. Returns an absolute CSname for the file associated with the 
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specified file instance. Implementation recommended for all CSNH servers. 
34.9.6. RENAMEOBJECT 



rcquestcode RENAMELOBJECT 

namcindex The byte offset of the old name relative to nameptr. 

namecontextid Context in which to interpret the old name. 

nameptr Pointer to the segment containing the old and new names. 

namelength Length of the segment containing die names. 



replycode Standard system reply code. 

context A Con textPal r identifying the named context 



Given a CSname for an existing object, this request binds a new name to the object and removes the 
binding of the existing name. Implementation is optional. 

The. new name must be absolute. (The initial "[" character is omitted.) It follows the old name in the 
segment, separated by a single null byte. The request fails, returning ILLEGAL.NAME, if the new name is 
in a portion of the name space not implemented by the object's current manager, and that manager is unable 
or unwilling to expand its name space as required. 

34.10. Context Directories and Object Descriptors 

An important aspect of system operation is supporting query operations about objects or sets of objects. A 
simple example is that of listing the names of all objects in a given context In general, one may wish to list a 
variety of information about objects in a context, perhaps ignoring some of the objects based on their 
properties. 

Each CSNH server implements a context directory for each context that it manages. A context directory 
appears as a file of records, with each record describing an object in the associated context. A directory file is 
accessed using the I/O protocol with the CREATEJNSTANCE request specifying the name of the context to 
be used. Hie FDI RECTORY bit is set in the mode field of such a request A client can then use the standard 
I/O routines to read the contents of the directory and derive the information required. The selection of the 
information required is done by the client not the server. The client may also be able to modify some or all 
of die fields of a directory record by writing it using tine standard I/O protocol. A server is not obliged to 
make all fields presented in a directory modifiable. If a client attempts to change a non-modifiable field, that 
field is left unaltered, but any other changes indicated in the request arc carried out 

The FDI RECTORY bit is primarily for the benefit of Vcrex-like file systems, which permit each node in 
the naming hierarchy to be (in UNIX terms) both a file and a directory. It discriminates between access to the 
data content of such a node, and Uic context directory associated with it 

Each record in a directory starts with a descriptor- type field that specifics the format of die record describing 
the object For space economy, this field is an identifier tiiat specifics a description of the record format 
stored elsewhere in a system database of such formats. (The standard formats and descriptor type identifiers 
arc defined in the header file <Vdircctory.h>.) Applications can read a directory and extract the required 
information by referring to the descriptor-type field and these format descriptions, even when a directory 
contains heterogeneous records. 

A similar query activity involves accessing the descriptor of a single object For.cfficicncy and consistency, 
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this is supported by a separate NREAD_DESCRIPTOR function on the object (as opposed to being 
subsumed by the context directory facility), which returns the same record as found in the context directory. 
A corresponding NWRITE.DESCRIPTOR operation is available for modifying an object's descriptor. 

A server need not store information about objects as it is presented in a context directory. For instance, the 
UNIX file system stores the names of files separate from their descriptors with the association provided by 
so-called "i-nodc numbers." A context directory entry in this case is fabricated dynamically by replacing the 
i-nodc number in each record by its descriptor. 

The standard descriptor reading and writing operations arc described below. The message formats used are 
described by the DescriptorRcqucst and DcscriptorReply structures defined in <Vdirectory.h>. 

* 

34.10.1. READ DESCRIPTOR and NREAD DESCRIPTOR 



requestcode NREADJDESCRIFTOR 

nameindex The byte offset of the name relative to segmentptr. 

dataindex The byte offset from the start of the specified segment where the returned descriptor is to 

be placed. 

namecontextid The context id of the context in which the given name is to be interpreted. 

segmentptr Pointer to a buffer that contains the object name and in which the descriptor is to be 

returned. 

segmcntlen Length of the buffer. 



requestcode READ.DESCRIPTOR 

filcid File instance id of the object whose descriptor is to be read. 

dataindex The byte offset from the start of the specified segment where the returned descriptor is to 

be placed. 

segmentptr Pointer to a buffer in which the descriptor is to be returned. 

segmcntlen Length of the buffer. 



rcplycode 



Standard system reply code. 



These request types provide a way of reading the descriptor (context directory entry) of a single object 
READ.DKSCRIPIOR specifics the object by file instance id, while NREAD.DESCRIPTOR specifics it by 
CSname. Implementation of both is recommended for all CSNH servers. 

34.10.2. WRITE DESCRIPTOR and NWRITE DESCRIPTOR 



requestcode NWRnE.DESCRIPrOR 

nameindex The byte offset of the name relative to segmentptr. 

dataindex The byte offset from the start of the specified segment where the new descriptor value 

begins. 

namecontextid The context id of the context in which the given name is to be interpreted. 
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segmentptr Pointer to a buffer that contains the object name and the new descriptor value, 

segmentlen Length of the buffer. 



requcstcode WRITEJ)ESCRIPTOR , 

fileid File instance id of the file whose descriptor is to be modified. 

dataindex The byte offset from the start of the specified segment where the new descriptor value 

begins. 

segmentptr Pointer to a buffer that contains the new descriptor value. 

segmentlen Length of the buffer. 



replycode 



Standard system reply code. 



These request types provide a way of modifying the descriptor (context directory entry) of a single object 
WRITE_DHSCRlPTOR specifics the object by file instance id, while NWRlTE.DESCRIPrOR specifics it 
by CSnamc. The server will modify each field in the object's descriptor for which the value written differs 
from the existing value, if the field is client-modifiable and the new value is legal. A client normally uses one 
of these operations by first reading the descriptor, then modifying the ficld(s) of interest, and finally writing it 
back. 



34.10.3. Multi-Manage rContext Directories 

A multi-manager context directory is implemented as multiple context directory files, one per manager 
participating in the context To list a multi-manager context directory, the client opens the context directory 
for each object manager in die context and then merges the object entries into a single list Merging the lists 
entails eliminating duplicates, since some objects in the context may themselves be multi-manager contexts, 
and will thus appear in several managers' directory files. All the context directories for a context arc opened 
in parallel, using a multicast CRKA TKJNS TANCE request To compensate for the inherently unreliable 
delivery of multicast messages and responses, a fbllowup message containing die list of managers from which 
replies were received can be multicast to the object managers. Only omitted object managers respond to the 
fbllowup message. For full reliability, additional followup messages can be transmitted until no more replies 
arc received. 

The format of a followup message is as follows. The message structure CreatelnstanceRequest, as 
defined in <Vioprotocol.h>, is used. 



requcstcode 

filcnamcindcx 

type 



filename 



filcnamclcn 



CREATEJNSTANCE.RETRY 

The byte offset of the start of the actual CSnamc, relative to filename. 

unspecified 

filcmodc 

contcxtid 

Identical to the corresponding fields of the original CREATEJNSTANCE request 

(chapter 33). 

Address of a data segment beginning with an array of process ids specifying the managers 
that should not reply to the request, terminated by a process id of 0. The CSnamc appears 
later in the segment as specified by filcnameindex. 

Length of the segment 
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The reply format is identical to that for CREATEJNSTANCE. 
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Since processes are the active entities in V, the kernel associates each V process with a particular user or 
account on whose behalf it is acting. Each authorized user within a V domain is assigned a unique user 
number, and each V process bears exactly one user number. 20 A process runs with the privileges associated 
with its user, and that user is considered responsible for its actions. An authentication server maintains a 
database of information about each user, including login name, personal name, encrypted password, user 
number, and preferred home directory. The authentication server supports simple queries on this database, 
which is keyed by user number and by login name. The authentication server will also set the user number of 
a requesting process if the correct password for that user number is presented in the request. 

The V authentication service docs not provide a very high level of security. Its main purpose is to provide a 
sense of user identity to programs that need to exhibit user-specific behavior, and to protect against 
inadvertent mistakes. Its design is grounded on the belief that the benefits of increased security in a research 
system tike V are very quickly outweighed by its cost in reduced performance and increased complexity. 

35.1. Authserver 

The authentication server itself is available as a program called authserver. Starting the server with the 
-d flag turns on debug output The -F flag, followed by a filename, specifies a non-standard authentication 
database file. 

The V executive automatically starts up an authentication server if none is running when a user attempts to 
log in. 

35.2. User Numbers 

In general, a process running with user number u has control over other processes running as user w, and 
over server-maintained objects owned by user u. Certain special user numbers arc exceptions to this rule, 
however. 

A process running with the predefined user number SUPERJJSER has total privilege to do anything that 
the kernel and servers implement. 'Hie authentication server runs as super-user. 

Somewhat more restricted privileges arc associated with the user number SYSTEM.USER. Server 
processes that need special permissions to enable them to act on behalf of other processes, but do not need the 
full SUPER.USER privilege level, run as SYSTKM.USER. 

User processes running on a workstation in the "not logged in" state have user number 
UNKNOWNJJSER. Hie UNKNOWNJJSER is somewhat more restricted than normal users, since not all 
processes running as UNKNOWN_USKR really belong to the same person. An unknown user on one 
machine is not allowed to manipulate processes belonging to unknown users on other machines. 

When a process is created, it initially has the user number of its parent The root process of each 
workstation's initial team is created with user number SYS'I'KMJJSER, allowing server processes on the first 
team to run as SYSTEM.USER if desired. User numbers can be queried with the User( ) kernel primitive 



20 
Processes on the same team need not all run under the same user number. 



V Sorters lUuncl986 



35*2 Authentication and the Authentication Serrer 

or changed with the SetU$erNumber( ) kernel primitive. 

35.3. Authentication Library Functions 

The following authentication functions are available in the standard V library. 



SystemCode AddUser(name, passwd, full name, home) 
char *name, *passwd, *fullname, *home; 

Add a new user with the given login name, password, full name, and home directory. Returns OK if 
successful, else a standard system code indicating the reason for failure. The requesting process must be 
authenticated as SUPERJJSER. Requires that an authentication server be running somewhere on the local 
network. 



SystemCode Authent1cate(name, passwd) 
char *name, *passwd; 

Authenticate the calling process as the given user, specified by login name. Returns OK if successful, else a 
standard system code indicating the reason for failure. Requires that an authentication server be running 
somewhere on the local network. 



SystemCode DeleteUser(name) 
char *name; 

Delete the user with the given login name from the authentication database. Returns OK if successful, else a 
standard system code indicating the reason for failure. The requesting process must be authenticated as 
SUPERJJSER. Requires that an authentication server be running somewhere on the local network. 



DestroyAuthRec(ar) 
AuthRec ar; 

Free each string in the given AuthRec 



char *Fu11UserName(p1d) 
Processld p1d; 

Return die full name of the user associated with the given process as a dynamically allocated string. The 
string should be freed by the caller when no longer needed, using free. Requires that an- authentication 
server be running somewhere on the local network. 



SystemCode MapUID(u1d, ar) 
UIO u1d; AuthRec *ar; 

Obtain an AuthRec containing the given user's authentication database entry. The user is specified by user 
number. Returns OK if successful, else a standard system code indicating the reason for failure. Requires 
that an authentication server be running somewhere on the local network. Note: this function dynamically 
allocates several strings to construct the AuthRec. The caller should invoke DestroyAuthRec(ar) when 
the AuthRec is no longer needed. 
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SystemCode MapUserName(name, ar) 
char *name; AuthRec »ar; 

Obtain an AuthRec containing the given user's authentication database entry. The user is specified by login 
name. Returns OK if successful, else a standard system code indicating the reason for failure. Requires that 
an authentication server be running somewhere on the local network. Note: this function dynamically 
allocates several strings to construct the AuthRec. The caller should invoke DestroyAuthRec(ar) when 
the AuthRec is no longer needed. 



SystemCode ModlfyUser(ar) 
AuthRec *ar; 

Modify the given user's authentication database entry to be as specified by the given AuthRec. The user is 
specified by the u1 d (user number) field of the AuthRec; a user with the given number must exist. Returns 
OK if successful, else a standard system code indicating the reason for failure. The calling process must be 
authenticated as the given user or as supcruser. Requires that an authentication server be running somewhere 
on the local network. 



SystemCode Password(name, passwd) 
char *name, ♦passwd; 

Check whether the given password is correct for the given user name. Returns OK if so, else a standard 
system code indicating the reason for failure. Requires that an authentication server be running somewhere 
on the local network. 



SystemCode SetUserNumber(p1d, u1d) 
Processld p1d; U1D u1d; 

Set the given process's user number to the given value. Returns OK if successful, else a standard system code 
indicating the reason for failure. The kernel places the following restrictions on setting user numbers: 

1. Any process can set its own user number to be UNKNOWN JJSER. 

2. Normal user processes are allowed to set the user numbers of dcsccndcnts to match their own. (This 
privilege is useful if a parent process must change its user number after having created other processes.) 

3. A process running as SYSTKM.USHR can set its own user number, or that of any dcsccndcnt, to match 
the user number of any process that is awaiting reply from it. (ITiis privilege allows servers to create 
processes that act on behalf of clients.) 

4. The SUPKRJJSER can set any process's user number to any value. 

UID User(pld) 
Processld p1d; 

Return the user number of the user associated with the given process. 

char *UserName(p1d) 
Processld p1d; 

Return the login name of the user associated with the given process as a dynamically allocated string. The 
string can be freed by the caller- using f ree( ) - when no longer needed. Requires that an authentication 
server be running somewhere on the local network. 
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35.4. Adding a New User 

The following is the recommended procedure for adding a new V user. See section 35.5 if you are installing 
V for the first time and need to add many users in one session. 

1. If you are using a UNIX host for file service, create a UNIX account for the new user. 

2. Under V, use the su superuser command to begin running as the V super-user. 

3. Run the V password program. 

a. Gick on the user name field, edit it to contain the user's desired login name, and hit return. 

b. Modify thejull name field to contain the user's personal name, in the .same way. 

c. Modify the home field to contain the V absolute pathname of the user's home directory. 

d. Click on ada\ and enter the user's desired initial password. 

e. Click on exit, or repeat to add more users. 

4. Run addcorr and answer the prompts. When it requests a password, type the user's UNIX 
password. 

35.5. Authentication Database 

There is one Vpassword file per network segment For each user it contains a uscrname, usernumber, 
password (using the same format as Unix), full name, and home directory. Each machine providing V 
filcscrvicc needs a user correspondence file, which lives in /etc/V. It maps between V user numbers and the 
local Unix account name of the corresponding user. 

The authentication server keeps its database in the file [sys]m1sc/Vpassword. This file should be 
made writcablc only by the V super-user. Ilic file format is similar, but not identical, to the UNIX password 
file. You can convert your UNIX password file to a V password file using the awk program provided in 
/etc/V/Vpassword . awk. 

ITic authentication server supports a simple form of password file replication. The first few lines of each 
file copy should list the absolute names of the master and all slave copies of the password file, as follows: 
master: [storage/pescadero/usr/V/misc/Vpassword 
s1ave:[storage/gregor1o/usr/V/m1sc/Vpassv»ord 
s1ave:[storage/navajo/usr/V/m1sc/Vpassword 

Whenever a new authendcation server starts up, it reads [sys]misc/Vpassword, which may come from any 
public Vscrvcr. When modifications arc made, it attempts to first modify the master file. If this file is 
inaccessible, no password files arc updated and the authscrvcr returns the standard reply code 
POWER- FA 1LER. If the master file is correctly updated then as many slave sites as possible arc also 
updated. 

Changes made when the master site is unavailable arc kept in the authservcr's in-memory database, so 
future updates may cause changes made when the master file server is up at a later dale. In general, users 
should refrain from changing the authentication database when the master password file is inaccessible. Hie 
design goal is to have a close- to-current password file available if the master site is down when the authscrvcr 
needs to be restarted. Redundant distribution of the master password file should be carried out to slave sites 
using rdist or similar tools on a regular basis. We do it every night 

Each UNIX system that makes its files accessible from V maintains a correspondence tabic mapping from V 
user numbers to UNIX login names. Sec section 43.1.1 for more information about correspondence tables. 
Another awk script /etc/V/Vusercorr . awk, is provided to create this table. 



*Thc user can run addcorr himsclfif you do not know his UNIX password. 
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The device server provides access to the raw kcmel-supportcd devices via the I/O protocol. It is 
implemented directly Jby the kernel as a pseudo-process as opposed to being a normal process like other 
system servers. Consequently, it is always configured when the V kernel is used. However, the device server 
behaves like any other I/O server process as far as applications arc concerned. 

The device server appears as a single process that supports different types of devices using the same I/O 
protocol. Access to a device is established by sending a create instance request to the pid returned by 
GctPid(DEVlCE_SERVER, LOCAL_PID), or, if using the standard name cache, by prefixing the device 
name with the context name "[device!" in a create instance request or Open() call. Using the standard 
information returned by the create instance request, the device can then be accessed using I/O protocol 
messages, either directly or by means of the standard I/O library routines described in chapter 22. There are 
also some device- specific operations defined for some devices. The currently supported devices are described 
below. r 

36.1. Ethernet 

The Ethernet interface is accessed by specifying a device name of the form enettt, where t is replaced by 
the Ethernet type, cither 3 for 3 Mbit experimental Ethernet, or 10 for standard Ethernet, and 5 is a suffix, 
which is null for the first Ethernet interface, a for die second, b for the third, and so forth. Currently only one 
Ethernet instance may exist at a time and only one Ethernet interface is supported, and the name ethernet is 
defined as an alias for cither enet3 or enetlO, whichever is present. 

The standard header file <Vcthcrncth> defines Ethernet-specific information, including the Ethernet 
packet format and various constants such as ENETJvlAXJMTA, the maximum size of the data portion of 
an Ethernet packet 

In a create instance request, the filcmodc must be FCREATE. 'Hie type of an Ethernet instance is always a 
readable, writcablc, variable block stream. 

Read and write instance requests arc standard except for the Ethernet block format The Ethernet is only 
sensibly accessed as a block (or packet) device, as opposed to a byte stream. The Ethernet block format is 
exactly that expected by the interface, namely, on the 3 Mbit Ethernet one byte for destination, one byte for 
source, two bytes for Ethernet packet type, followed by some number of data bytes, and on the 10 Mbit 
Ethernet six bytes for destination, six bytes for source, two bytes for packet type, followed by data bytes. The 
number of bytes specified in a write and returned by a read includes the destination, source and type bytes as 
well as the data bytes. 

An Ethernet-specific QUERY_K1LE request is supported that returns the host number, the number of 
collisions, receiver overflows, CRC errors, receiver synchronization errors, transmission timeouts detected, 
and the number of valid packets received. The host number should be used as the source address for every 
packet transmitted. The format for the request and reply messages is given by the Query EnctRcqucst struct 
defined in <Vcthcrncth>. 
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36.2. Disk 

The disk interface is accessed by specifying the device name diskO or diskl. These names correspond to the 
first and second drives attached to the interface, respectively. Currendy, only the Xylogics disk interface is 
supported. 

In a create instance request, the filcmodc must be FCREATE The type of the disk instance is always 
readable, writeable, multi-block. 

Upon "opening" a disk device, the disk driver reads the label off of the first sector to obtain disk-specific 
information (such as the number of cylinders, number of heads, etc.). The disk label must have previously 
been written to the disk using the diskdiag program. JThe format of ja disk label is defined in 
"/V/kcrnel/m68k/disklabel.h". 

Read and write instance requests are standard and allow a maximum of DISK_MAX_BYTES (as defined in 
"/ V/kcrnel/m68k/xyl.h", usually 64 kbytes) bytes to be accessed. The disk driver translates from a (block, 
byte count) pair to a (cylinder, head, sector, sector count) tuple. 

A disk-specific QUERY.FILE request is supported that returns device access statistics (e.g„ the average 
seek distance per I/O). A MODIFY.FILE request allows these statistics to be modified (e.g., reset to zero). 
The format for the QUERY JFILE reply message is given by the QucryStoragcRcply struct defined in 
<Vstorage.h>. 

36.3. Mouse:The Graphics Pointing Device 

The mouse is a graphics pointing device. It provides a means of indicating a coordinate position plus 
signalling different states via its three buttons. The device server provides access to the mouse through the 
I/O protocol, thus viewing it as a file. 

The mouse file appears as a 10-bytc file divided into 3 major fields. The first two bytes specify the mouse 
button positions, the three buttons being the low-order three bits of the second byte. A bit with value 
indicates the button is up, otherwise down. 'Hie next 4 bytes specify its current X coordinate. The last 4 bytes 
specify its current Y coordinate. The kernel updates this file according to the input from the device. These 
fields arc specified in <Vmousc.h> as buttons, xcoordinate and ycoordinate with MBUITON1, MBinTON2 
and MBU1TON3 specifying the button bit field assignments in the buttons field. 

A create instance request for a mouse specifics the name mouse in the filename field. Only one mouse and 
one instance of that mouse arc currently supported, '[he filcmodc field of the create instance request must be 
FCREATK. Hie mouse file instance created is initialized to have X and Y coordinates of 0. It has type 
attributes READABLE, WRITEABLE, and FIXED.LENGTH. 

Read and write requests must specify block and a byte count of 10 bytes. A read instance request returns 
10 bytes specifying the current state of the mouse "file." A read instance request is queued until a change to 
the mouse file occurs, providing no change has occurred since the last read request Thus, for instance, a 
mouse reader process that repeatedly reads from the mouse and updates a cursor is suspended when the 
mouse is not being moved and no button positions arc changing. Conversely, the read returns every time a 
change docs occur. 

A write instance operation changes the kernel-maintained record of the mouse button positions and the X 
and Y coordinates to that specified by the 10 bytes in the buffer. Setting the mouse buttons in the kernel has 
no significant effect because this record is updated to agree with the actual button positions on the next input 
(or "squeak") received from the mouse. 

There is no need to provide a query function that simply returns the current mouse position because that 
should always be stored outside the kernel. 'lTiat is, the application decides where the mouse is; the kernel 
simply updates the position relative to the absolute position specified. 

The kernel docs not provide any scaling of mouse movements. That is left to the application. 
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36.4. Serial Line 

The kernel device server provides access to raw serial lines through the serial device. Two serial lines are 
supported, but only one instance for each may exist at a time. 

In a create instance request, the name serialO or seriall specifies a serial line. The filemode must be 
FCREATE. The instance id returned is used for output; the instance id + 1 is used for input Parameters for 
the input instance can be obtained using Querylnstance. 

Each serial line is a pair of streams, one readable and one writeable. Characters read from each serial line 
are buffered in the kernel until a process reads from the device, but the buffer is rather small, so a user who is 
interested in input from a serial line should keep a process "listening" to it at all times. The serial line device 
docs not provide any echoing of input characters, nor does it convert input editing or conversion of newline 
characters to a carriage return/line feed sequence on output 

The serial device drivers support QueryFile and ModifyFile operations to allow changing such parameters 
as the data rate, bits per character, and the state of the modem control outputs DTR and RTS. The necessary 
message structures and constants for these operations arc defined in the standard header file <Vserial.h>. (At 
this writing, the Query and Modify operations are not implemented in the Sun-1 serial device driver.) 

36.5. Console 

The kernel console device is intended to provide a measure of hardware independence to programs doing 
interactive character stream input and output The console device provides access to the console keyboard 
and display of the workstation the kernel is running on, independent of the type of workstation. On 
workstations whose keyboards arc connected to serial line 0, reading from the console device reads from serial 
line 0; on others, it reads from the port to which the keyboard is connected. Likewise, on workstations with 
frame buffers, writing to the console device draws characters on the frame buffer; for those without writing to 
the console sends output to serial line 0. In cases where the console uses serial line 0, instances for serial line 
and the console may not both exist at the same time. 

A create instance request must specify filemode FCREATE, and name console. The console device is a pair 
of streams, one readable and one writeable. As with the serial line device, the instance id returned by a 
Crcatclnstancc is writeable, and that instance id + 1 is readable. The parameters of the second instance can 
be obtained using Querylnstance. Both instances are marked INTERACTIVE, but SET PROMPT and 
SETJMKA K .PROCliSS arc not support .*d. 

Console device input is buffered in the same way as serial line input (sec above). The console device does 
not provide any echoing or output conversion, but it docs make an effort to sound the workstation's beeper 
when an ASCII BEL character is output 

The console device is automatically opened by the kernel upon creation of the first team, and is ordinarily 
never closed. 

36.6. Framebuffer 

'llicrc arc device drivers available for 

36.6.1. Sun framebuffers 

The current Sun (and Cadlinc) drivers allow one to enable and disable video output through modify file 
requests. The device may be opened and modified, or may be modified directly with a NMODlFY_FILE 
request The following routine turns the framebuffer off: 
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^include <Vframebuffer.h> 
FbOff() 

{ 
ModlfyFramebufferMsg *req; 

req.sysCode - NMODIFY«-FILE; 

req. request ■ FB OFF; 

req. name Index - 0; 

req.nameptr ■ "[devlcejframebuffer"; 
req.namelength - sizeof("[dev1ce]framebuffer"); 
NameSend( &req ); 



36.6.2. MicroVaxQVSS Framebuffer 

Caution is advised when using this device driver. Opening the device maps the QVSS frame buffer memory 
into one's address space. One cannot directly access the framebuffer until the device has been opened. To find 
where the framebuffer has been mapped, perform a QUERYJNSTANCE on the file and look at the field 
uiC&jMOTtrtiieullEHls driver allows direct user access to QVSS device registers. The device is 
made up of six sixteen bit (short) blocks referencing the first six device registers. More information can be 
found in the top secret DEC Engineering specification VCB01-KP. /V/kernel /vax/qvss . h defines all of 
the useful control bits. 

The registers available are: 

Control Status 

1 Cursor X position (not used by the V-System) 

2 Mouse Position (x 1s low byte, y 1s high byte) 

3 Spare 

4 CRT controller address pointer 

5 CRT data 

36.7. Null Devices 

Two null devices arc available, and arc normally configured into ail versions of the V kernel. The nullin 
device is a readable, 0-lcngth file; it thus returns an end-of-file indication on every read attempt The nullout 
device is an endless sink for output. 
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When a process incurs an exception, it causes a trap which is fielded by the kernel. The kernel effectively 
causes the process to send a message to the exception server with the contents of the message describing the 
exception incurred. If there is no exception server, the kernel prints an error message and disables the 
faulting process by causing it to send to itself, which permanently blocks the process. 

The exception server checks to sec if another exception handler has registered for this process or an 
ancestor. If so, it forwards me message to the handler. For ordinary programs, arrangements arc made for 
such messages to be passed on to the V debugger. The format of the exception request and registration 
messages are defined in <Vexccptions.h>. The only request types supported are EXCEPTION.REQUEST 
and REGISTER.HANDI.ER. EXCEPTION.RKQUEST messages should only be generated by the kernel. 
The REGISTER J-IANDIiiR request code is used both for registering and dercgistcring handlers. 

If no process was registered, the exception server prints a message on the screen indicating die type of 
exception, the pid of the faulting process, and the instruction, program counter and status register at the time 
the exception occurred. The exception server then destroys the faulting process, thus preventing it from 
doing further harm. Note: the program counter may have been incremented beyond the actual instruction 
incurring the exception so it should not be considered exact, although the error message routine attempts to 
find the correct PC by searching for the opcode of the instruction that was reported in the exception message. 

The error printing routine used by the exception server is available to other exception handlers as the 
library routine StandardExceptionHandler. 



V Servers 12 March 1986 



38-1 



— 38 — 
Exec Server 



The exec server is the central control facility for all instances of the V system executive on a workstation. Its 
purpose is to allow sharing of code and data (such as aliases) among all executives. The intention is that while 
each executive is a separate command stream, all executives on the same workstation should present the same 
command interface to the user. That includes customized aspects of that command interface, such as aliases. 
Since the exec server is part of the basic environment of the V system, such customization do not vanish even 
if the terminal agent (i.e., the VGTS or STS) is replaced; they remain as long as the user is logged in. 

The exec server allows programs to have instances of the executive (usually referred to simply as "execs") 
created and destroyed. An exec is known to the server by its exec id; exec ids are small integers starting at 0. 
There is currently no concept of ownership of execs; any program can destroy any exec regardless of whether 
it created it or not. 

The exec server is located by 

GetP1d(EXEC_SERVER, L0CAL_PID) 
It is present in all the standard configurations of the Vsystcm. 

The following requests are supported. 
CREATE_EXEC Creates an executive, with standard i/o and context specified in the request message, and 
returns the exec id. 

START_EXEC Under some circumstances an exec is not started by the CREATE_EXEC request, because 
the requestor needs to do some SetlnstanccOwncr operations first. START.EXEC then 
allows the exec to start running. Normally all this is transparent and is handled in the 
CrcatcExec library routine. 

DELETE_KXEC Delete an executive. If there is a program running under it, it is abruptly stopped due to 
the death of its parent process. 

KILL.PROGRAM 

Kill the program running under an executive. If there was no program running under that 
executive, nothing happens, 

QUERYJiXEC Returns information on an executive; its status (free, loading a program, or running a 
program), its process id, and the process id of the program running under it, if any. 

CHECK_EXEC Makes a check of all executives. If the standard input server or standard output server of 
an exec has died, the exec is destroyed. This is used mainly when changing terminal 
agents. 

The message structure for the requests, the request values and the logical identification of the exec server 
can be found in the header file Vcxcch. 
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The internet server is an I/O server that provides network communications using any of several protocols. 
It is essentially a protocol converter which allows applications which communicate by means of the V I/O 
protocol to communicate with hosts which can only (or prefer to) be reached by some other protocol. As 
such, the server has been structured in a manner which allows easy addition and deletion of protocols. The 
server consists of a general framework which is independent of the particular protocols being supported, and 
one or more protocol-specific modules. Each module implements a particular protocol and must interface 
that protocol to the requirements and facilities provided by the server's general framework. Currently the 
DARPA Internet protocols IP and TCP are supported. " 

39.1 . Running the Internet Server 

The internet server can be compiled as an independent V program, or linked into another program. As an 
independent V program, it is often loaded automatically some other V program (c.g„ by telnet), so that users 
usually don't need to invoke it separately. 

The standard V command "internetscrycr" may be run in the background to provide a local internet server 
on any workstation. The internet server program by default will only register the server for the logical id 
INTERNETJSERVER on a local basis. There arc two optional switches that may be used when starting an 
intcrnctscrven The -g option causes the internet server to register itself globally so that it can create 
connections for hosts anywhere in the V-Systcm. This facility allows local hosts to avoid spending some 100K 
of memory for this server. 23 The -d # option causes the internet server to enable debug messages up to a 
severity of "#" (an integer in the range [0..9]; is the default). 

To include the internet server in another V program, have it create a process which executes the function 

In 1tInternetServer( local Flag, debugFlag) 

1nt localFlag; /* True 1f internetserver should be local. •/ 
int debugFlag; /* True if debug output should be printed. */ 

and cause the linker to search die V internet library when loading the program (i.e., add -IVintcrnct on the 
C compilation command line), it is generally preferable to run die internet server on its own team by 
invoking the internet server program described above, rather than linking it into another program. 

39.2. Accessing the Internet Server 

Once the internet server has been started it can be accessed using die V I/O protocol plus the protocol- 
specific requests and parameters specified in <Vnet.h>. 
A CREATE JNS VANCE request to the internet server must specify the mode FCREATR It results in the 



22 Thc Xerox PUP protocol is no longer supported (starling with V-Systcm version 5.2). We continue to show the PUP protocol in 
some of the examples of this section for illustrative purposes only. 

23 Using a global internet server can degrade performance if many connections arc being supported simultaneously. For bursty 
applications such as telnet connections, however, any performance degradation from using a global internet server is typically small 
enough to go unnoticed. 
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creation of two instances, one of type READABLE, VARIABLE_BLOCK, and STREAM, the other of type 
WRITEABLE, VARIABLE.BLOCK, and STREAM. The parameters of the writcable instance are returned 
in the Create I nstanccReply. 'Hie readable instance has an instance id equal to the id of the writcable instance 
plus 1; its parameters can be obtained using QUERYJNS TANCR Although the internet server does not 
implement the full naming protocol (see Section 34), it does implement context directories. Thus, commands 
suchasHstdlr -1 [Internet/local] return useful information. 

An internet server connection is owned by the process which requested its creation. Ownership of a 
connection can be passed on to another process by means of the SETJNSTANCEJDWNER request If the 
owner process should die then the connection is aborted. 

39.3. DARPA Internet Protocol (IP) 

Possession of an IP network instance provides a process access to the network for sending and receiving IP 
packets of a specific IP protocol type. Differing IP instances are delineated by the protocol field in the IP 
packets. Any protocol id value may be specified when creating the instance except for those values already 
taken. For example, the value for TCP, is already taken by the TCP implementation inside the internet server 
itself. Creating an instance with protocol yields a "promiscuous" instance that receives all protocol types 
which have not been specified by any other active IP instances. 

IP network instances expect WRITEJN STANCE to supply completely packaged IP packets. 
READJNSTANCE similarly will return complete IP packets. This approach allows IP instances to remain 
connectionless in concept and thus avoids the overhead of establishing a network connection instance for each 
different set of IP packet parameters. (Remember that READ and WRITE under the I/O protocol don't 
allow for specification of parameters.) 

To open an IP network instance, use CREATE JNSTANCE and specify the protocol by overlaying the 
IpParms structure definition in Vncth onto the unspecified field of the CrcatclnstanccRcqucst structure. 
QUHRY_FILE will return the value of the protocol field for an IP instance. MODlFY_FILE has no meaning 
for these instances. A standard library routine "Opcnlp" is provided to allow creating an IP instance and 
allocating a File structure for it, for use with other I/O library routines. 

39.4. DARPA Transmission Control Protocol (TCP) 

TCP file instances created by the internet server implement DARPA TCP byte stream connections. There 
arc three minor differences from the specification in the DARPA Internet Handbook. First, die "push flag" 
is always set - data written is transmitted over the network as soon as possible. (Buffering of data is 
performed by die I/O library routines and wouldthus be redundant.) Second, the urgent data flag is not set as 
part of a write operation. Instead, a MODIFY _FILK request is used to set the urgent data flag immediately 
before a write operation containing urgent data. The urgent data flag is reset immediately after the write 
operation and thus must be set using a MODlFY_FILE request before each urgent data write operation. 
Third, there is no concept of connection timeout provided. Connections are aborted if their owner process 
goes away. 

Two variants of CREATHJNSTANCE arc permitted on instances of type TCP, corresponding to the 
Active and Passive opens of the Internet Handbook. Note that the foreign host must be specified completely 
when issuing a CKEA TEJNS TANCE request with the active bit set A standard library routine, OpcnTcp, is 
provided to allow creating a TCP instance and allocating a File structure for it, for use with other I/O library 
routines. 

Two types of release mode arc supported for REl.EASEJNSTANCE requests corresponding to the Close 
and Abort primitives of the DARPA specification, respectively RH1 , .STANDARD (equal to 0, the normal 
release mode defined by the V I/O protocol) and RFL_ABOR T. Releasing die writcable instance closes the 
client's end of the connection. Data can still be read from the readable instance until the other end closes. It 
is necessary to release both the readable and writcable instances to deallocate a connection. 
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Since TCP supports the concept of a byte stream, the READJNSTANCE and WRITEJNSTANCE 
operations do not segment the data flow in any way. (There is one exception: when a packet is received with 
the urgent flag set, the next READJNSTANCE receives a BEGIN_URGENT_DATA reply code with zero 
bytes of data. A similar zero-length reply of END_URGENT_DATA is returned when the point in the data 
stream indicated by the urgent pointer is reached.) Any READJNSTANCE requests outstanding when a 
TCP connection closes for whatever reason arc replied to with a rcplycode indicating the reason. An attempt 
to read from a closed connection is signaled by an END_OF_FILE reply code. 

The QUERY JHLE operation may be used on TCP instances to find out the state of the TCP connection. 
MODIFY J^ILE may be used to change various parameters of the connection. The structure TcpParmsl in 
VneUi defines the parameters which can be set both at CREATEJNSTANCE time and by means of a 
MODIFY J^LE request The meaning of the fields are defined in the internet Handbook. TcpParms2 
defines both parameters which may be set and state variables which may not be set but whose values are 
returned if QUERY_FILE is executed with TcpParms2 specified. The parameter in TcpParms2 which may 
be set is sndUrgFlag. This parameter is used to signal urgent data. The rcvUrgFlag field returns whether or 
not urgent data has been sent from the remote host and not yet received. The bytcsAvail field indicates how 
many bytes of data arc waiting to be received by the user. The state field indicates what state the connection 
is in with respect to being open, listening, established, closed-waiting-for-remotc-closc, etc. (see the Internet 
handbook). 

39.5. Adding New Protocols 

This section should be of interest only to persons who wish to add an additional protocol to (or remove one 
from) the internet server. It describes the specifications governing the interactions between particular 
communications protocols and the general framework of the internet server. 

There are two interfaces that a protocol must deal with: the external interface to clients of the internet 
server, and the internal interface to the general communications facilities provided by the server's framework. 
The external interface consists of the operations, message formats, etc. that the protocol must understand in 
order to interface with a client's V I/O connection. The internal interface consists of the routines, message 
buffer conventions, etc. that the protocol implementation must respectively use or provide in order to send 
packets to the network and receive packets from the network. 

39.5.1. External Client Interface 

The external interface to a protocol is dictated for the most part by the V I/O protocol specification. 
Interaction between a client and the internet server is by means of a V I/O connection and the only variations 
that can be effected arc by means of the Query File and Modify File operations. Thus clients open a 
connection by means of the Create Instance operation, they read and write data by means of the Read Instance 
and Writclnstancc operations, they determine the general state of a connection by means of the 
Qucrylnstancc operation, and they close a connection with the Release Instance operation. 

A connection is "owned" by the client process which sent its Crcatclnstancc request, but can be transferred 
by means of a SctlnstanccOwncr request. The semantics of ownership arc that a connection must be aborted 
if its owner process dies. One of the general facilities provided by the internet server is monitoring of the 
existence of connections' owners. However, the protocol implementation module is responsible for providing 
an abortion routine. 

Protocol-specific interactions arc handled by means of the QucryFilc and ModifyFilc operations. Protocol- 
specific instantiation parameters can also be specified as part of the Crcatclnstancc operation. The QucryFile 
operation is used by the client to determine the state of protocol-specific connection variables: the ModifyFilc 
operation is used to modify these variables. Thus the manner in which tilings such as the "Urgent Data 
Notification" facility in TCP must be implemented is the following: 

1. The client's Rcadlnstancc operation returns an exception code indicating that something out of the 
ordinary has happened. 
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2. The client docs a QucryFilc operation to determine the protocol-specific state of the connection and 
obtains the "Urgent Data Notification" on return. 

Similarly, a client wishing to signal "Urgent Data" on a TCP connection must do so with a ModifyFilc 
operation. 24 

39.5.2. Internal Protocol Interface 

Protocol implementations must interface both to the external internet server client and also to the internal 
environment of the server itself. This internal interface consists of the following components: 

1. A network packet buffer module which all protocols must use. This module provides a pool of packet 
buffers which have a standardized header format so that various general facilities can manipulate them. 

2. A process structure specification for the protocol. All protocol implementations must define certain 
processes and be aware of the existence of certain other processes. Part of this specification is a 
specification of the message interactions between these processes. 

3. A set of protocol-independent routines supplied by the server which all protocol implementations must 
use for such things as writing packets out to the network, obtaining and returning packet buffers, etc. 

4. A set of protocol-specific routines supplied by the protocol implementation which arc used by the 
general server facilities to return incoming network packets to a connection, signal timeout conditions, 
etc. 

These components will be described in more detail in the following subsections. 

39.5.2.1. A Brief Overview Of The Internet Server's Structure 

The internet server consists of the following processes: 

1. A connection-establishment process. This process registers itself as the internet server logical id and 
waits for connection creation requests from new clients. For each new connection creation request it 
invokes a creation routine for the protocol specified in the request This routine is responsible for 
setting up a connection and its associated data structures and handling proccss(cs). 

2. Connection handling processes. Each protocol connection is handled by one or more separate 
processes. It is up to the protocol implementation to decide how to structure the connection handling 
processes for a connection. However, one of these must be designated the "primary" connection 
process. This process will be responsible for handling all communications with the rest of the internet 
server. 

3. A network reader process. The V kernel Allows only one network device instance to exist at any time. 
ITie network reader process reads packets from the network device and calls a protocol-specific routine 
for each protocol being supported. The protocol-specific routines invoked arc responsible for 
determining which connection of their protocol type a packet should be given to. The network reader 
process runs at the highest priority allowed so that it can read and multiplex incoming network packets 
before they arc overwritten by subsequent packets in the kernel device. 

4. Two timer processes. The first timer is a timeout timer which wakes up periodically and invokes a 
timeout checking routine for each connection. If the timeout check for a connection returns a time 
which is less than the current time then a message is sent to that connection's primary connection 
handling process. The timer determines how long to sleep before waking up again by keeping track of 
the minimum timeout time beyond the current time. 'Hie second timer checks whether any connection 
owners have died. A message is sent to the primary connection handling process of each connection 



*54 

llic reason why the V I/O protocol specification has been structured in this manner is for reasons of efficiency. Hie vast majority of 
data read and write operations done on a connection arc done with "normal" settings for the connection parameters. By removing 
parameter specification from the read and write operations these operations can be executed more quickly. 
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whose owner has died signalling that the connection should be aborted. This second timer wakes up 
once every 5 seconds. 

39.5.2.2. The Packet Buffer Module 

The packet buffer module provides a set of routines which manage a pool of packet buffers which arc used 
as the medium of data transmission inside the internet server. These packet buffers are handed between 
various parts of the internet server by means of pointers (to avoid copy operations) and their header format 
must be understood by all parts of the internet server. 

The header format for packet buffers is the following: 
typedef struct pbuf 

struct pbuf *next; /* General purpose link field.*/ 

1nt length; /* Length of the data in the buffer. */ 

char *dataptr; /* Location of the start of the 

data. */ 

unsigned unspedf ied[2]; /* Scratchpad fields. •/ 

char data[MAXPBUFSIZE]; /• The actual packet buffer. */ 
} *PktBuf; 

The next field allows packet buffers to be placed in various queuing data structures. The dataptr field points 
to the start of the data in the data array. Packets arc typically constructed starting from the back of the data 
array, with various headers progressively added on to the front The unspecified fields are intended for 
storing various packet-specific items of information. They are used as scratchpad working areas, 
MAXPI3UFSIZE must be large enough to accommodate all packets encountered by the internet server. It is 
set to die maximum allowed packet size of the physical network. 25 

The routines provided by packet buffer module are the following: 
PktBuf AllocBuf(); 

DeallocBuf(pkt); 
PktBuf pkt; 

Duffers arc handed out one at a time by means of calls to AllocBuf(). Buffers arc returned to the free pool by 
calling l)calloclJuf(). These routines manipulate the buffer pool in an atomic manner; so diat they can be 
used from multiple processes without conflict 

39.5.2.3. Process Interactions 

The implementation of a protocol connection must deal with die network reader and the two timer 
processes in a prescribed manner. In order for these processes to know whom to send messages to each 
connection must have a "primary" process associated with it Hie process ids of these primary processes are 
stored in a global data structure maintained by die internet server which contains one entry per connection. 
The details of this data structure will be described in a later subsection. 

Network Reader Interactions 

llic network reader process must run at high priority and cannot afford to do much processing because it 
must always be ready to accept incoming network packets before they arc overwritten in the kernel device by 
subsequent packets. This has led to an interface format between die network reader and die various 
connection handling processes where communication is by means of atomically updated queues of packet 



•ye 

Note (hat there is only one packet buffer size for the entire internet server. A single buffer size was chosen primarily for reasons of 
simplicity. Mi lending the packet buffer module to handle multiple bulTcr sizes would not be difficult 



HTiat Is, it must be able to keep up with the (possibly many) hosts that arc sending it packets. 



V Scncrs 12 March 1986 



39-6 Internet Senrer 



buffers. The network reader process enqueues packets for a connection by calling the KnQucueSafcO routine, 
which places a packet in a specified connection queue. This routine is non-blocking (i.e. no message traffic 
involved) so that the reader process can immediately continue on to process any additional packets that may 
have arrived from the network. The connection handling processes then remove packet buffers from their 
queues by calling the DeQueucSafeO routine. The definitions for these two routines arc as follows: 

EnQueueSafe(pkt, q) 
PktBuf pkt; 
RlngQueue *q; 

DeQueueSafe(q) 
RlngQueue *q; 

RingQueues are atomically updated queues which are defined in the general internet server module. They 
must be initialized with calls to the lnitSafcQueue() routine: 

In1tSafeQueue(q, MngBufs) 

RlngQueue *q; /• Queue header. */ 

RlngBufRec r1ngBufs[]; /* An array of MAX_RING_BUFS queue 

records. */ 

RingQueues consist of the following two data types: 

typedef struct 

{ 

RlngBuf head; 

RingBuf tall; 

} RlngQueue; 

typedef struct RlngBufType 

{ 

PktBuf pkt; 

struct RingBufType *next; 
} RingBufRec, *R1ngBuf; 

The RingQucuc structure defines a header record for die queue. RingliufRccs arc the actual queue elements, 
and arc placed in a circular list by the InitSafcQucucO routine. 27 The pkt field of a UingBufRcc is used to 
point to the packet buffer which is enqueued by it 

Note that at most MAX_.RlNG_.nUKS packet buffers can be enqueued in a RingQucuc. KnQucueSafcO 
returns if it can't enqueue a packet buffer. 

There is one caveat to the above description of how the network reader interacts with individual 
connections. The primary connection handling process for a connection may be blocked waiting on client 
requests 28 so that the packet buffer queue cannot be processed until a request message is received. To take 
care of this case each primary connection process must also set a variable indicating whether it is blocking 
awaiting client requests or not 'Hie network reader checks this variable when enqueuing a packet for a 
connection and sends the connection a "wakcup" message if it is blocked. Hie process receiving the message 
must reply immediately to this message in order to minimize the time that the network reader is blocked. 

Another point to be made here is that the actions for the network reader described above (i.e. invocation of 
KnQucueSafcO and checking to sec if a "wakcup" message must be sent) arc actually part of the protocol- 
specific "network reader" routine that each protocol must supply as part of its implementation. This will be 
described in more detail later. 



27 
"ITic reason why a circular queue of this form is needed stems from the problem of maintaining these queues in an atomic manner. 

28. 
Fhc protocol implementations to date have consisted of a single process per connection which alternately waits on client requests 

and processes its packet buffer queue. 
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Timer Interactions 

The two timer processes communicate with connections by means of "timeout" messages. Whenever a 
timeout condition is detected by a timer process it sends a message to the relevant connection process 
indicating that a timeout condition has occurred. The message format employed is the following: 
struct timeoutMsg 

{ 
SystemCode requestcode; /* Standard message request code 

field. */ 

short unused; 

unsigned timeoutCondltlon; /* Which timeout has occurred. */ 

unsigned unusedl[6]; 

}; 

The requestcode field is the same as that used for all other message requests. However, instead of a 
"standard" V I/O protocol request code an internet server-specific request code signalling timeout is used. 
The timcoutCondition field specifics which timeout condition has occurred. 

39.5.2.4. Protocol-Independent Interface Routines and Data Structures 

Global Data Structures 

There is one global data structure that must be maintained by all active connections in the internet server. 
This is the NctlnstTablc, which contains an entry for each connection specifying various V I/O protocol- 
specific parameter values, the process id of the primary connection handling process, and a pointer to a 
control block associated with that connection. The V I/O protocol parameter information is used by the 
Query lnstancc() routine for answering Query Instance requests about connections. 'ITic process id is used by 
the network reader and timer processes to find the primary process for a given connection. ITie control block 
pointer is used to access connection-specific information. It is intended for use by the protocol-specific 
network reader and timeout checking routines. 

The primary manner in which connections manipulate the NctlnstTablc is through the following two 
routines: 

int AllocNetInst(prot, ownerPId, pid, rblockslze, wblocksize, tcbld) 
1nt prot; /* Instance protocol type 

(TCP, PUP, ICMP, etc.) */ 
Processld ownerPId; /* Process 1d of owner of the 

connection. */ 
Processld pid; /* Process id of primary connection 

handling process. */ 
1nt rblockslze, wblocksize; /* Block sizes for resp. read and write 

V I/O connection Instances. */ 
unsigned tcbld; /* Pointer to the control block for 

this connection. */ 

Deal locNet Ins t( index) 

1nt index; /* Index of NetlnstTable entry to 

deallocate. */ 

AlIocNctlnstO returns an index into the table where the newly allocated entry has been placed. Individual 
fields can then be set by indexing through this value into the table. (E.g. SctlnstanccOwncr requests would be 
dealt with in this manner.) 

Each protocol implementation is expected to employ these routines to manage the NctlnstTablc in a correct 



ITicsc requests arc actually directed at the conncct : on handling processes themselves, implying that each connection could employ 
its own Query Instance routine. However no benefit would be gained by such duplication. 
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manner. I.e. allocation and deallocation of NetlnstTablc entries is not done automatically by the server's 
general facilities. 

Useful But Not Essential Routines 

The internet server provides several generally useful but not essential routines which may be employed by 
protocol implementations if they so chose. These include the following: 
SystemCode Querylnstance(rqMsg) 
QuerylnstanceRequest *rqMsg; 

Boolean Inva11dF11e1d(rqMsg) 
IoRequest *rqMsg; 

ReplyToRead(replycode, pid, packet, bufferPtr, length) 

SystemCode replycode; ' /* Reply code to send to a reader. */ 

Processld pid; /• Process id of the reader. */ 

PktBuf packet; /• Packet buffer containing data to 

return to the reader. NULL if 
there is no data to return. */ 
char *bufferPtr; /• Address of reader's buffer. */ 

int length; /* Length of data to return. */ 

QueryProcess() 

QucrylnstanccO returns the state of a specified network connection. It is V I/O protocol-specific and hence 
independent of the particular network protocol being supported by the other end of the connection. It 
obtains its information from the NetlnstTablc entry for the connection. Connections arc specified in the 
request message in the same manner as with all other V I/O connections, namely by a filcid. 

Invalid FilcidO checks whether the filcid field in a client's request message is reasonable; i.e. whether it maps 
to an existing connection entry in NetlnstTablc which is in use. All incoming client requests should be 
checked with this routine to avoid corruption of other connections' control blocks. 

RcplyToRcadO is a generic routine for replying to a client's read request It performs the MovcTo 
operation needed to move data from a packet buffer to the client's read buffer and packages an appropriate 
reply message. 

QucryProccssO is a routine which runs in its own process and is used for debugging. It provides a means 
for examining and changing the state of the internet server while it is in operation. 

39.5.2.5. Protocol-Specific Interface Routines and Data Structures 

There arc two types of protocol-specific routines diac a protocol implementation must provide: network- 
level routines and connection-level routines. Network-level routines arc used by the network reader process 
to multiplex incoming network packets to the correct connection. Connection-level routines arc used to 
initialize a protocol, create a new connection and interface with the connection timeout checking process. 

Protocol implementations arc usually done for pmtocol families rather than individual protocols. For 
example, the current internet server implements both the IP and the TCP Internet protocols. However, rather 
than implementing these two protocols as separate modules, they arc implemented together, so that the TCP 
module can make use of facilities already defined by the IP module. This results in a situation where only the 
IP module interfaces with the network layer and the TCP module interfaces internally to die IP module. Thus 
the IP/TCP protocol family implementation has three interfaces to the rest of the internet server rather than 
four: it has a single network-level interface and a connection-level interface for both IP and TCP respectively. 

Protocol-specific interface routines arc accessed by the general server facilities through function tables 
indexed by protocol type. 'Micro arc two such function tables, one for the network-level routines and one for 
the connection-level routines. The format of these tables is described below. 
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Network-level 

The network-level function tabic is called PnctTablc and is defined as follows: 
struct PnetBlock 

unsigned prot; /* Network protocol type. */ 

Boolean active; /* True 1f a network connection is 

active for this protocol. */ 
int (*1n1tN)etProt) (); /* Initialization routine for this 

protocol . */ 
int (*rcv) (); /* Receiving routine for this 

protocol . */ " 
} PnetTable[MumPnetProtocols]; 

The first two fields arc actually not functions. The prot field is used to store the network protocol type id so 
that the network reader process can figure out which table entry to use for a given network packet 

The active field is used to allow the network reader process to "short circuit" discarding of broadcast and 
invalid packets for inactive protocols. Without this field the reader process would have to call the rcvO 
routine for these packets since it can't tell itself whether they should be discarded. The active field is 
managed through the following two routines: 
Act1 vateNetProtocol (prot) 
1nt prot; 

DeactlveateNetProtocol(prot) 
1nt prot; 

prot specifics which table entry to access. 

Associated with the active field is another table, called NctLcvclProtocol, which is used to map from 

connection protocols to the network-level protocols which support them. For example, the IP/TCP protocol 

implementation described previously would designate both IP's and TCP's network-level p.-otocol as being 

IP. 'ITic definition of the table data structure, along with an example initialization is as follows: 

1nt NetLevelProtocol[NumProtocols] ■ 

{ 

0, /* IP •/ 

0, /• TCP */ 

1, /* PUP */ 
/• ICMP */ 

}: 
The index of each entry corresponds to the index of the corresponding protocol entry in the FuncTablc 
table. The contents of each entry is the index of the corresponding network-level protocol in the PnctTablc 
table. Thus, in the example shown, the FuncTablc defines the IP protocol at index 0, the TCP protocol at 
index 1, the PUP protocol at index 2, and the ICMP protocol at index 3. The PnctTablc defines the IP 
network-level protocol at index and the PUP network-level protocol at index l. 30 'ITic inilNclProt field 
specifics an initialization routine for the protocol which is called at server boot time. 

The rev field specifics a routine which is called whenever a network packet arrives which has a protocol type 
equal to that specified in the prot field of the entry (and the active field is true). This routine is responsible 
for figuring which connection of its protocol, if any, should receive the packet. If a connection is found dicn 
the routine is responsible for enqueuing the packet in that connection's RingQucuc (using die KnQueueSafcO 
routine) and for checking to make sure that the connection's processes) will actually be able to process the 
enqueued packet buffer (i.e., if the connection's proccss(cs) arc rcccivc-blockcd awaiting client requests Uicn 



ITic actunl internet server code uses manifest constants instead of integers to fill these fields - making things much more readable 
I lowcvcr, lo illustrate the principle, no manifests were employed. 
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the routine must send a message to "wake" them up). Packets for which no connection is found must be 
returned to the free buffer pool with a call to DcallocBufQ. 

The interface definition for the initNctProtO and rcvO routines is as follows: 
In1tNetProtocol() 

ReceiveProtoColPkts( packet) 

PktBuf packet; /* Ptr to the Incoming network 

packet. */ 

where InitNctProtocolO and RcccivcProtocolPktsO are example names. 

Connection-level 

The connection-level function table is called Fundable and is defined as follows: 
struct FuncBlock 

{ 

■int. (*In1tProtocol) (); 

SystemCode (*CreateConnect1on) (); 
int (*NextTimeout) (); 
} FuncTable[NumProtocols]; 

The InitProtocol field specifics an initialization routine for the protocol which is called at server boot time. 

The CrcatcConncction field specifics a routine which is called by the connection-establishment process 
when a client requests the creation of a new connection instance. The routine must create the data and 
process structures for a new connection and then handle the Crcatclnstancc request from the client 3 This is 
usually also the place where a call to the ActivatcNctProtocoK) routine is made to signal that the protocol is 
active. 

The NcxtTimcout field specifics a routine which is called by the timeout checking timer process. This 
routine returns the time of the next timeout for its connection. If that time is already past then the timer 
process will send a timeout message to the connection's primary process. The connection's data structures are 
accessed through the tcbld field of the connection's NctlnstTablc entry. 

'Hie interface definition for the InitProtocolO, CrcatcConncction(), and NcxtTimcout() routines is as 
follows: 

In1tProt() 

CreateProtConnection(reqMsg, cl1entP1d) 
CreatelnstanceRequest reqMsg; 

/* Createlnstance request message sent 
by a the client. */ 
Processld clientPId; /* Process 1d of the client. */ 

NextProtT1meout( tcbld) 

unsigned tcbld; /* Ptr to the control block for the 

connection. */ 

where InitProt(), Create ProtComicctionO. and NcxtProtTimcoutO arc example names. 



The method recommended for doing this is to have the routine create the connection handling processes) and then forward the 
Crcatclnstancc request to the connection's primary process. This allows the connection handling processes) to manipulate their own 
data structures (which arc typically kept on the processes)' stack(s)). 
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39.6. Monitoring and Debug Facilities 

Normally the internet server runs in the background and is accessed using the standard mechanisms 
discussed in the previous sections. In situations where poor network or protocol behavior is suspected, it is 
often useful to inspect the internal state of the internet server and to observe the behavior of particular 
connections. 

A simple approach to debugging or monitoring involves starting an internet server in debug mode (e.g., 
1 n ternetserver -d 5, where the debug level "5" is useful for debugging or monitoring a wide range of 
potential problems). Much of the debug information provided details the operation of TCP/IP connections, 
though some information about the V I/O protocol and other protocols is also reported. 

Upon startup, the internet server reads the configuration database for the workstation on which it is running 
and prints out information about how it will route to various internet addresses. This information typically 
takes the form shown below (for a workstation with internet address 36.8.x.y): 

IP Gateway Table: 
36.8 -> local 
36 -> 36.8.0.4 
default -> 36.8.0.1 

The host at 36 . 8 . . 4 is a gateway that can route to subnets within net 38 (Stanford), while the host at 
36 . 8 . . 1 is a gateway that can route to all non-Stanford hosts. This routing information is often useful in 
determining whether the configuration database for the workstation is set up properly. See Section 19 for a 
description of the V-Systcm configuration database. 

More flexible debugging is possible using a separate V program that is provided specifically for this 
purpose. There arc many advantages to this approach: an internet server that is already running can be 
examined, and non-local internet servers can be inspected to name two. Typing 

1n query 

to a V executive will start a program that can be used for more advanced inspection (and modification) of 
the internal state of the internet server. Inqucry will attempt to find an internet server on the local machine. 
If none can be found, or if a different internet server is of interest, the user must type additional commands as 
described below. 

Once the inqucry program has started, it will prompt for single letter commands. Most commands are 
intended for low-level debugging by program maintainors and arc not described in detail. The commands 
that may be useful for user-level monitoring arc described below in approximate order of usefulness: 

? list available commands (including brief description). 

A attach to the debug I/O stream of the internet server. The default is for debug I/O to go to 

stdout (as defined at the time the intcrnctscrvcr program was invoked). You must always 
use tilts option when inspecting non-local internet servers. 

U unattach from the debug I/O stream of the intcrnctscrvcr (returning it to stdout). One 

typically uses "d 0" to turn of debug output before unattaching (since sending output to 
stdout is not always what is wanted). 

d change the verbosity of the debug information mat is printed. The user is prompted for a 

digit in the range [0..9], where (the default) indicates silence and 9 indicates full verbosity. 
A value of 5 is appropriate for most user-level debugging, as this will cause only the most 



ITiis is a temporary mechanism until more complete standards for internet routing in local network environments can be defined 
and implemented. 
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"interesting" events (e.g., retransmission of packets, bad packets, unusual events) to be 
reported. The effect of this command is identical to the -d command line switch that 
can be given to the internet server at startup. 

R reattach to (or relocate) an internet server. User is prompted for the process id of the 

internet server of interest (or to mean the local internet server). The inqucry program 
can only communicate with one internet server at a time. 

V print version informatin about the internet server currendy being inspected (workstation 

name, compilation date and time). 

f lists free resources (e.g., buffers and network instances). 

n list some basic information about active network instances. 

p show detailed information about a particular network instance. Only implemented for 

TCP instances. Primarily useful to maintainers — see the DARPA Internet Handbook for 
clues to the meaning of this information. Fields of possible interest at the user-level 
include counts of retransmissions, out-of-order packets and packet delays (10ms units). 

x immediately exit the internet server — abort any existing connections. The inquery 

program continues to run — use R to reattach to an interact server. 

Q quit out of the inquery program (leaving the internet server running). The U and d 

commands arc often used before using Q. 

For typical user-level monitoring of a local internet server, the "A" command followed by the "d 5" 
command are the only commands that should needed. They allow a user to observe the frequency of 
retransmissions, receipt of bad packets, and other unusual events. This may be helpful in identifying the 
source of poor performance — flakey networks or gateways, incorrect or inefficient TCP/IP implementations, 
or just long network delays. 



V-Systent 6.0 Reference Manual 



40-1 



— 40 — 
Memory Server 



The memory server (or memserver) simulates a V storage server, storing files in main memory that is 
otherwise unused. It has no concept of file protection. It otherwise supports the standard V I/O and naming 
protocols. A file "foo" managed by the mem server can be accessed by referring to [storage/localjfoo or 
[storage/wsnamejfoo, where wsname is the name of the workstation where the memserver is running. 

A memory server is not part of the standard first team, but one can be started by using the memserver 
command (you will usually want to run this command in the background). On startup, the memory server 
checks that no other memory server or storage server is running on the workstation, to avoid name conflicts. 

By default, the memory server will allocate as much main memory as it needs to store the files that it 
manages. It could thus use up all remaining main memory, if it so desired. The -m and -k flags can be used 
to place an upper bound on how much main memory the server can use for file storage, memserver -m 
100K, for instance, limits the amount of storage space to 100K bytes, memserver -k 10 OK, on the other 
hand, sets Uie storage space limit to 100K bytes less than the total free memory that is currently available. 
('M* can be used in place of 4 K' to indicate 'mega' bytes.) 
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The pipe server is an I/O server that implements a synchronized stream file called a pipe. A pipe is a 
unidirectional flow-controlled communication channel between two processes using the standard I/O 
protocol. V pipes are similar to Unix pipes. 

A pipe file instance is type STREAM, VARIABLE_BLOCK, and READABLE (for the read end) or 
WRITEABLE (for the write end). 

In response to a CREATEJNSTANCE request, the pipe server creates an instance of a pipe, which is 
actually two file instances representing the read and write ends of the pipe. The file id returned in the reply to 
the CREATEJNSTANCE request is the file id of the write end. The file id of the file instance for the read 
end is one greater than the file id for the write end. The file instances arc owned initially by the processes 
specified in the readowner and writeowner fields of the CrcatcPipcRcqucst. When a pipe is created, it is 
allocated a fixed number of buffers between 2 and 10 as specified by the buffers field of the 
CrcatcPipcRcquest. Include <Vpipe.h> in a program to define CrcatcPipcRcquest 

Pipe synchronization provides that a request to read a block that has not yet been written is queued until 
that block is written. Also, a request to write a block when the current buffer limit for the pipe is exceeded is 
queued until buffer space is available. 33 A request to read from an empty pipe whose write file instance has 
been released is replied to with an END_OF_FILE reply code. When the read end file instance is released, 
unread data is discarded and the data of subsequent writes to the write instance arc discarded with the write 
returning successfully. A pipe no longer exists when both the read and write instances arc released. The pipe 
server periodically checks that the owners of both file instances of the pipe exist. When the server determines 
that the owner of an instance no longer exists, it effectively releases that instance. 

The pipe server is located by 

server_pid * G9tPid(PIPE_SERVER,AMY_PID) 
where the pipe server may be local to the workstation or located on a server node. 

The pipe server can be compiled as an independent V program or included in another program. To include 
the pipe server directly in a V program, call the function In1tP1peServer( ) at the start of the program 
and cause the linker to search the pipe server library when loading the program (i.e., add -IVpipe on the C 
compilation command line). The standard V command pipescrver may be run in the background to provide a 
local pipe server on any workstation. The V executive automatically starts up a local pipe server if there is not 
one available when a pipe is needed. 



33 
Actually only one reader and one writer arc queued: the rest arc replied to with a Rt: I'RY reply code. 
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42.1. Overview 

The team server manages the teams of a host (Teams usually correspond to programs -although a 
program may consist of more than one team.) Specifically, it performs the following functions: 

• Accepts requests to load teams. Requests can originate both locally and remotely, with the team server 
deciding whether or not remote execution requests will be accepted. 

• Accepts requests to terminate teams. 

• Implements a director/ of all currently running teams. This directory can be read using the standard 
directory listing protocol. 

• Implements round-robin scheduling for teams. Teams can be run in foreground, background, or guest 
mode. Typically, locally invoked programs arc run cither in foreground or background mode. 
Remotely executed programs arc only allowed to run in guest mode, which is lower in privilege than 
either foreground or background mode. The team server also provides 4 real-time priority classes that 
run ahead of the three round-robin classes, and a "stopped" priority that ensures that no process on a 
stopped team will run. 

• Registers itself as the exception handler "of last resort." The exception server forwards process 
exception messages to the team server if no one else ha* registered themselves for them. The team 
server invokes a postmortem debugger on the team of the process that incurs an exception. 

• Responds to host state information requests. This is the mechanism upon which host selection for 
remote execution of programs is based; 

• Acts as an agent for migration of logical hosts (i.e. remotely executed guest programs). 

The team server resides on the "first team" of a host, i.c., it is considered to be a system server that is always 
present on a host and is loaded automatically when a host is booted. Various operations that the team server 
performs, such as team creation and team execution priority setting, arc privileged operations that only 
processes on the first team may perform. 

42.2. Team Loading 

The team server is the only process that may create and load new teams. 'ITic library routines 
LoadProgram and ExecProgram provide the user interface to this function. 'ITicsc package up an 
appropriate request to the team server and take care of matters such as setting up the team environment 
block. The team server only creates a new team and loads down its object code from a designated open file 
instance. Setting up parameters and setting initial execution priority and stack size is left to the team load 
requestor in order to allow control over the order of events. This is necessary for programs such as debuggers 
which wish to allow users to set breakpoints and examine die code before a team actually starts to run. 

Load requests to the team server also specify who the "owner" of a team is. Teams arc destroyed if their 
owner process goes away (same semantics as for processes created by other processes). Teams can optionally 
be specified to be owned by themselves, dius permitting Uicm .to outlive Uicir load requestors. 

Teams owned by the themselves arc run in background mode, all others arc run in foreground mode. 
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42.3. Team Termination and Exit Status Values 

A teams can be terminated by having its root process destroyed using the DestroyProcess kernel 
operation, or it can exit voluntarily by calling the ex1 1( ) library routine or returning from ma1 n( ). 

Calling ex1t( ) or returning from ma1 n( ) allows an exit status to be associated with the terminating team. 
Note: By convention, teams that arc destroyed without having called ex1t( ) or returned from ma1n( ) are 
considered to have exit status -1. 

The team server also terminates any teams whose owners have died. It uses a timer process to periodically 
query the state of all teams which the server thinks are still running and their owners. 

42.4. Host Status 

The standard context directory listing protocol (see section 34.10) can be used to obtain information on all 
teams that are currently running. The command 

Ustdlr [team/local] 
lists teams running on the local host, while the command 

Ustdlr [t e am/ hostname'} 

lists teams running on the named host 

To obtain information on a specific tcam only, an NREAD.DESCRIPTOR request can be made. The 
command 

Ustdesc [team/local ][b1n]te!net 

prints information about a program running locally that was invoked under the name [b1n]te1net. The 
tcam of interest can also specified by setting the request message's contextui field to the team's root process id; 
in this case the CSnamc (character string name) in the message should be null. 

The team server also keeps track of host resource information such as the number of teams running, 
processor utilization, memory resources available, etc. It returns this information to requests it receives for 
host status information. These request messages arc used primarily to implement host selection for remote 
execution of programs. Request messages can specify resource requirements and the tcam server will only 
reply if its resource state information conforms to the specified requirements. Request messages arc typically 
sent to the well-known process group of all tcam servers (sec include file Vgrouplds . h), although they can 
be sent directly u> a particular tcam server. (Sec the library routine Query Hosts for more details on remote 
host selection.) The command 

Ustdlr [team/ hostname'] 
lists all tcam servers (and hence all hosts) on the network. 

42.5. Remote Execution 

line implementation of the tcam server and team-loading library routines is such that load requests can be 
made to both local and remote leain servers, thus allowing for transparent rcmole execution of V programs. 
In order to assure the priority of local requests the tcam server keeps track of the state of the local host and 
uses tliis information to determine whether or not a remote load request will be accepted. 

Currently the system's host selection facilities will not select hosts on which a user has logged in. However, 
remote execution requests may still be sent to the tcam servers of such hosts and they will be accepted. This 
policy allows debugging programs to be executed on a host even when it has "hung" with a user logged in. 
The policy depends on the goodwill of users to not circumvent the standard host selection facilities. The -x 
option of the 1 og 1 n command can be used to disallow all remote execution requests. 
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42.6. Round-Robin Scheduling 

The team server implements a round-robin scheduling scheme for all teams except the first team and the 
workstation agent team (typically either the vgts or the STS). These are typically run at real-time priority 
levels 3 and 4 respectively. As mentioned, teams can be run either in foreground, background, or guest mode. 
Foreground teams have priority over background teams, which have priority over guest teams. 

Scheduling actually employs an additional team priority value for its implementation: a higher (i.e. more 
privileged) running priority. The running priority is used to implement the concept of a "time-slice" so that 
one team can't block out all other teams of the same priority. 

Team priorities are user-settable with the ChangeTeamPrloMty operation, which allows users to request 
that the priority class of a team be changed, subject to authorization privileges. Users may change the priority 
of any team on a workstation they arc logged in to, even if the ChangeTeamPMor 1ty request is sent from a 
remote location. Guest users of a machine cannot change their priority to anything other than guest or 
stopped. 

42.7. Exception Handling 

The team server is the exception handler of "last resort.'* It invokes the standard debugger in "postmortem 
mode" on the team of a process that has incurred an exception. 

The debugger is invoked with the -d flag, so if the VGTS is in use, the debugger will pop up a new window 
for its command interaction. If the VGTS is not running on the workstation, however, the debugger will use 
the same standard I/O as die root process of the team that has incurred the exception, and may thus come up 
in a state where it is competing with an input reader process in the team incurring the exception. This can 
prevent input from reaching the debugger, in which case the debugger will not be of much use. 

42.8. Migration 

The team server's duties also include acting as an agent for migration. If a logical host is to be migrated 
from another machine then the team server must first accept the request and then act as a local agent for its 
implementation. Implementation includes setting up initial descriptor information in the local kernel and 
team server, and then participating in the transfer operation of the actual descriptor information. 

The team server also implements usage policies with respect to migrating guest logical hosts (i.e. remotely 
invoked guest programs) away from the local machine, llic current usage policy is to migrate guest programs 
whenever a user logs into the machine. 
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The V Unix server is a Unix program (and not a V program or command) designed to simulate a V 
kernel/storage server on a VAX Unix system (currently only Berkeley Unix 4.2 or 4.3). It provides access to 
some of the Unix system services via the V kernel interprocess communication primitives. To workstations 
running the V kernel, the Unix server appears as a standard V server, primarily providing Unix file access 
using the standard V I/O protocol. Note: Unix servers are also frequently referred to as V servers. (Someday 
we may even implement such a server for an operating system other than Unix.) 

Unix servers, like true V storage servers, implement the V-System naming protocol. The Unix system's 
complete directory tree is rooted at a node called [storage/Aos/name]. where hostname is the name 
returned by the Unix gethostname( ) routine (converted to lower case). A Unix server may be either 
public (if it is started with the -p option), or non-public. A public Unix server implements the generic name 
[storage/any, and therefore such a host must maintain the up-to-date versions of all the standard V- 
Systcm files and commands. On the other hand, hosts that run non-public Unix servers are not required to be 
kept up-to-date. 

43.1. Sessions 

If a V server is running on a Unix system, then remote access to the resources of this system is provided by 
session processes. Sessions arc 'forked' copies of the main V server, each dedicated to a particular V user 
number. Like the main V server, each session appears externally as a regular V process. On each Unix host, 
the main V server, plus all of its sessions, belong to a local V process group. The 'group id' of this process 
group is usually used to communicate with the Unix server. 35 As mentioned above, each session is dedicated to 
a particular V user number. Any message that is sent to the common group id will be handled by the 
particular session that is responsible for that message's user number. (If no such session exists, then the main 
server will create one automatically.) lTic distribution of incoming packets to the individual sessions is 
handled by die packet filtering code in the Unix kernel (sec the "installation notes" for further details). 

Warning: As an optimization, the packet (liters for each session currently assume that the high-order 16 bits of each user 
number arc zero. Thus, one should beware of using user numbers higher than 6S53S. lhis restriction is likely to be 
eliminated in future releases of the system. 

43.1.1. User Correspondences 

The main V server always runs as 'root'. The Unix uid of a session, however, is determined by a V-to-Unix 
user correspondence table, which is a mapping from V user numbers to Unix user names. The user 
correspondence tabic is maintained as a lile on each Unix host. The name of this file is given by the macro 
USKK.CORRI'SI'ONDI'NCILHLIi defined in the header file conflg.h (in the Unix server source 
directory). (At Stanford, this file is named /etc/V/Vusercorrespondence.) For security, the user 
correspondence file should be writcable only by "root". The file should contain user correspondences for at 
least the following V user numbers: 

(SUPER JJSKR), and 1 (SYSTEM JJSER) 



34 
hostname can also be set by starting the server (Vservtr) with the -n option. 

Individual pids arc used for file instance I/O, however. 
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These should correspond to whatever Unix account is used to manage V-System files on 
Unix (although preferably not "root"). 

2(UNKNOWN_USER) 

This should correspond to a Unix user with very few privileges. 

43.1 .1 .1 . Adding and Deleting User Correspondences 

If a user correspondence for a particular V user number is not present in the user correspondence file, then 
the user correspondence for the V UNKNOWN_USER is used instead. That is, a session for a V user who 
docs not have a user correspondence will run with the same permissions as a non-logged in user. In addition, 
such users arc not permitted to execute programs remotely on the Unix host (see section 43 J). 

A V user can use the (V) add com program to create (or modify) a user correspondence on any Unix host 
(provided that it is running a V server, of course), addcorr repeatedly prompts for a host name, then a 
(Unix) user name and password on this host. It then attempts to create a new user correspondence. (If tliis is 
successful, then any existing correspondence for the V user will be removed.) 

The del co rr program can be used to delete an existing user correspondence, del co rr repeatedly 
prompts for a host name, and attempts to delete an existing user correspondence for the V user on this host. 

The V SUPER_USER can use addcorr and del cor r to modify user correspondences for any V user (not 
just for SUPERJJSER). (In this case these programs will also prompt for a V user name.) 

The following additional points should be noted: 

• When a user correspondence for a V user on a particular host is added/modified (using addcorr) or 
deleted (using del cor r), then any existing session for the V user on this host will be destroyed. 
(Subsequently, a new session will still be created automatically, if needed.) 

• The V UNKNOWNJJSER is not permitted to modify his own user correspondences. 

• For security, the Unix servers do not allow user correspondences to be made to "root", nor to Unix 
accounts with a null password. 

• If your current context is a Unix V session, then the (Unix) who ami program can be executed remotely, 
in order to show the Unix uid of this session. (Recall that the (V) name program can be used to show 
your exec's V user number.) 

43. 1 .2. Lifetime of Sessions 

A session will die automatically if it has been inactive for a certain period of time (defined by 
MAXJJESSIONJNACTIVITY in conf 1g.h-l5 minutes at Stanford), and if it is not maintaining any 
instances with valid owner pids. 

43.2. File Access 

When a session receives a CREATEJNSTANCE request, it attempts to open the named file. If the session 
has the correct permissions, then an instance is created, with the type Held set according to the request mode. 
Files opened in FREAD mode arc of type READABLE FlXEl)J,ENGTH, and MULTIJILOCK. Hie 
modes FCREATE and FMODIFY create instances of type READABLE, WRITEABLE, and 
MULTIJH.OCK. FAPPEND mode adds the further constraint of APPEND.ONLY. All instances are 
random access, but operations must start on a block boundary. The block size of these instances is equal to 
the maximum appended segment size for V kernel messages. 

if tlic mode is FCREATE, or it is FMODIFY and the file docs not exist, then a new file is created along 
with the associated instance. Files arc created with Unix lile protection bits ("mode bits") set to allow reading 
and writing by the owner, and reading by group and others. This protection mode is given by the macro 
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DEFAULT CREAT MODE, defined in conflg.h. A client may change the mode bits using a 
WRnE_DESCRIPTOR or NWRITE.DESCRIPTOR request 

43.3. Program Execution 

A client can execute Unix programs through a V session by sending a CREATEJNSTANCE request with 
the FEXECUTE flag set in the mode field. The name and arguments of the program to be executed arc sent 
in the segment with the NULL character being a field separator. The last argument need not be null 
terminated. The context in which the program is.to be executed is also specified in the request 

Given a request the session has a built-in search path that it uses to determine which Unix program to 
execute. This search path is given by the macro PROGRAM_SEARCHJPATH, defined in conf 1 g . h. 36 The 
session tries to find the first file in a directory along the search path that matches the given name. If the name 
contains a 7\ then the search path mechanism is not used and only the context specified in die request is 
searched. If the program is a shell script the Bourne shell is invoked cxplicidy, and it determines which shell 
should execute the script based on the normal Berkeley Unix conventions. As a side-effect the shell expands 
any wild-card characters (such as '*' and T) found in the arguments. This expansion docs not occur if the 
Unix program is not a shell script 

After all of the preliminary checking is done, the session forks and its child attempts to run the program. 
The parent process replies to the requestor with an OK status. However, there is no guarantee that the 
execution will be successful. A failure can occur after the OK reply has been returned, since the program is 
not loaded until the child has been forked off and the reply is sent asynchronously. If a failure of this, nature 
occurs, then an error message should appear in the program's output 

In the reply message, the session includes an instance id for the running program. If the file mode in the 
CREATEJNSTANCE request was FREAD, then the instance id specifics an instance of type READABLE, 
VARIABLE.BLOCK, and STREAM. The client can read the program's standard output using this instance. 

If die mode was FCREATE, FMODIFY, or FAPPEND, then the instance returned in the reply message is 
of type WRITEABLE, VARIABLEJM.OCK, APPKND.ONLY, and STREAM. Data written into this 
instance is piped into the program's standard input An instance with id 1 greater than the one returned in the 
reply is also created, of type READABLE, VAR1ABLEJJLOCK, and STREAM. Reading from this instance 
provides access to the program's standard output 

When the program terminates (cither normally or abnormally), the session returns an END_OF_FILE 
reply to any write requests. Read requests will continue to be accepted as long as data is left in the pipe. 
Write requests will block if the pipe is full and the Unix program is not reading from it. (Unix pipes can 
buffer up to 4096 bytes of data.) 

A client may terminate the program by releasing all instances associated with it If only one of the instances 
is closed, the program will not terminate immediately. This alfows a client to close the program's input and 
have it clean up before exiting. One should be careful not to release the readable instance before program 
termination, because Unix sends a signal to any program tiiat writes to a pipe with only one end. The signal 
will kill the Unix process, if the process is not catching or ignoring it 

43.4. File Descriptors 

The server supports V context directories and descriptor requests. One can open a Unix directory with the 
FDIR ECTOR Y flag set in the mode field and the server will automatically translate standard Unix directory 
entries to V Unix file descriptors. Directories arc not writcablc directly, but descriptors can be modified using 
a WRITE DESCRIPTOR or NWRTTE_DESCRlPTOR request The UnixFileDescriplor type is defined in 



Alternatively, the search path can be found by executing the Unix command prlntenv. This will display the environment 
variables that arc passed on to programs executed via the session. 
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the system include file <Vd1 rectory . h>. 

43.5. Debugging Sessions 

It is possible to turn on debugging output from a session (or the main server), by 'killing' it with the 
SIGTSTP signal. Debugging output is redirected to the file /tmp/VserverDebug/t, where n is the (Unix) 
pid of the server or session. To turn off debugging output, kill the process with the SIGTSTP signal once 
again. Warning: Debugging should be turned off as soon as possible, because this file quickly gets to be very 
big. Note that debugging output is likely to be of use only to wizards. 

If your current context is a Unix V session, then the (V) Instances program can be used to find out the 
status of whatever file instances this session is maintaining at the time. 
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Workstation agents are a generic class of server used In the V-System. A workstation agent has the duty of 
mediating between the .workstation hardware, the user, and the other programs in the system. It is responsible 
for line editing functions,e.g. the fact that the back space key does not add a backspace character to the input 
stream but deletes a character from the input stream. It translates the newline character *\n' into a carriage 
return/linefeed sequence on workstations that require it It is also responsible for interacting with the exec 
server to create at least one executive, or providing means for the user to do so. It may, but need not, support 
multiple i/o streams. Workstation agents may differ for two reasons: because they arc designed to offer 
different services to the user, or because they are designed to run on different types of workstations. 

The V system currently contains two different workstation agents, the Simple Terminal Server (STS) and 
the Virtual Graphics Terminal Server (VGTS). The Simple Terminal Server is a minimal workstation agent 
It provides a single i/o stream, using the terminal facilities provided by the kernel console device, and creates 
one executive using that i/o stream. The standard V line editing interface is provided, but no mouse or 
graphics facilities are available. The Virtual Graphics Terminal Server, in contrast, provides a very large set of 
facilities: multiple i/o streams in multiple windows, graphics, and mouse-controlled menus. But it supports 
die same line editing facilities. A large class of programs should be able to run under either of these 
workstation agents, or any other workstation agent, without any knowledge of which workstation agent is 
present 

The newtcrm command allows the user to replace the workstation agent on his workstation without 
rebooting the workstation. 

44.1. Implementation of Workstation Agents 

These arc the requests that should be supported by a workstation agent at the minimum: 

• It should support the V I/O protocol for INTERACTIVE.STREAM files. In simple cases, it may give 
polite replies to CRIiA TEJNS TANCK and RKLEASty NSTANCK without really doing anything, as 
the STS docs. 

• It should support the QueryPadRequest and MocMfyPadRequest messages in the fashion 
expected by Qu eryP ad () and Modi fyPad(). Inparticular,Mod1fyPad(f He, 0) should turn off 
all "cooking", giving the client access to the raw, unadorned terminal. 

In addition, the following conventions should be observed, in order to allow the newterm command to 
work: 

• Upon starting up, the workstation agent should join the local workstation agent group. 

• It should support the Die request message, which is a polite way of asking the workstation agent to 
expire. 
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The Simple Terminal Server (STS) is a minimal terminal agent It does not use graphics, and it takes up less 
memory than the VGTS. Only one I/O stream is supported. A program that wants to do graphics directly on 
the SUN hardware, not mediated by the VGTS, should be run under the STS. 

The STS creates one executive. If this executive is ever destroyed, by encountering end of file or by other 
means, it will be replaced within a second or so. Such a replacement can be forced by the sequence control-t 
x. A program running under the executive can be killed by control-t k. The normal tZ and tC commands 
also work, but they can be disabled by Modi f y Pad () requests, while the control-t sequences cannot be 
disabled. 

45.1 . STS Line Editing Facilities 

The STS provides a superset of the line editing facilities that are provided by the VGTS. All 
Mod1fyPad() bits that are not related to the mouse work as they do under the VGTS: CRJnput, 
LF_Output, Echo, Lincbuffer, PagcOutput, PagcOutputEnablc, and DiscardOutput 

As well as the line editing commands described in section 2.5, the STS also supports the following 
commands: 

CTRL-1 Re-display the input buffer. 

CTRL-n Move cursor down one screen line. 

CTRL-p Move cursor up one screen line. 

CTRL-q Quote next character. Control characters arc displayed as *tC 

CTRL-y Move the contents of killbufFcr into the input buffer, inserting at the current cursor 

position. 

CTRLA Insert next character with the eighth bit set Character is displayed as '\nnn\ where nnn is 

the octal representation of the character code. 

ESC-, Move cursor to the beginning of the input buffer. 

ESC-. Move cursor to the end of the input buffer. 

ESC-backspace Same as EiSC-b. 

KSC-d Kill from the cursor to the end of the current word. 

KSC-Dl-L Same as ISC-h and CTRL-w. 

ESC-t Transpose the two words preceding tine cursor. 

45.2. Hardware Environment 

The STS communicates with the user via the kernel console device. If the workstation has a framebuffer, 
characters arc sent to the terminal emulator built into the workstation's PROM monitor; otherwise, characters 
arc sent through serial line to a character terminal. 
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The attached terminal or terminal emulator must understand the escape sequences sent to it by the STS for 
cursor positioning. The STS currently works properly with the following terminal emulators and terminals: 

• Any PROM monitor terminal emulator that supports ANSI standard escape sequences, e.g., the SMI 
PROM monitor. 

• Cadlinc PROM monitor terminal emulator. 

• Any character terminal that supports ANSI standard escape sequences, e.g., VT100 or Hcath-19 in 
ANSI mode. 

45.3. Remote Terminal Server 

The Remote Terminal Server (RTS) supports the same interface as the STS, but encapsulated in the ARPA 
TELNET Protocol; its standard input and output are normally a TCP connection opened by the telnet server 
(p. 4.1). Like the STS, the RTS uses execs created by the local exec server; this may lead to difficulties if there 
is another telnet or local user on the same host, as the exec server assumes it serves only one user at a time. 

The RTS violates the standard protocol on two points: it insists on echoing input (under the control of 
client programs) even if the ECHO option is not successfully negotiated, and it docs not send go-aheads as 
may be required by some hosts to support half-duplex terminals. These violations are typically not a problem 
in paracticc, as most user Telnet implementations support these options. All other options arc properly 
refused. 

The RTS works with the Hcath-19 terminal (in ANSI mode), the VAT provided by the VGTS, the SMI 
PROM monitor, and possibly others. 
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The Virtual Graphics Terminal Service (VGTS) allows the display of structured graphical objects on 
workstations (with appropriate displays) that run the V system. This chapter describes how the standard 
library routines interface to the VGTS, as well as describing some of the VGTS's internal structure. 
Applications programmers usually need not concern themselves with the details of this section; instead they 
should consult the "Graphics Functions" section of the manual (section 29). 

46.1. Current VGTS Versions 

There are currently two working versions of the VGTS. sunlOOvgts is used on workstations with SMI 
model 100 framebuffcrs, while sunl20vgts is used with the SMI model 120 framcbufYcr. (Sun model 50 
workstations also use the model 120 framebuffcr.) Users usually will not have to concern themselves with this 
distinction, since tearal-vgts (the default first team) automatically loads the correct version of the VGTS 
shortly after it begins running. Furthermore, the program vgts is a 'bootstrap' program which loads the 
correct version of the VGTS (in a new team), and then dies. Thus, "vgts" can be given as an argument to 
newterm (see Section 4), regardless of the workstation's framebuffer type. 

The difference in VGTS versions is important, however, when loading special first teams that have a VGTS 
already linked in. teaml+sun 100 vgts will run only with a SMI model 100 framebuffer, and 
teaml+sunl20vgts only with a model 120 framebuffer. 

46.2. AVT Escape Sequences 

Unless otherwise noted, ail escape sequences can come with or without the optional left bracket between 
the escape and the escape command character. Arguments to the escape command arc decimal character 
strings separated by a semicolon. 'Itic following subset of drc ANSI standard escape sequences is decoded by 
the SUN VG'IS terminal emulator: 

BBLL Causes some form of audio feedback (buzzer, bell, etc.) if possible, and flashes all the 

views of the AVT. 

TAB Positions the cursor at next multiple of eight (plus one) columns, erasing characters 

between the current cursor position and the new position. WARNING: this behavior is not 
VT1 00 compatible and is subject to change. 

FF Clears the AVT. 

CR Returns the cursor to the first column of the current line. 

LF NcwLinc - Moves the cursor down one line. If it is at the last line of the scrolling region, 

all lines in the region move up (scroll). 

BS Cursor moves backwards one space. 

50 Shift Out -Select the Gl character set. Currently ignored. • 

51 Shift Out- Select the GO character set. Currently ignored. 
NUL Null - ignored; may be used for padding. 
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DEL Delete -- ignored; may be used for padding. 

ESC A Cursorllp -- move the cursor up one line. 

ESC [/ A CursorUp -- move the cursor up i lines. 

ESC B NcwLine -- move the cursor down, as with LF. 

ESC [i B NcwLine -- move the cursor down the / lines. 

ESC C CursorForward -- move the cursor forward, but do not overwrite the character at the 

current position. 

ESC [i C CursorForward - move the cursor forward /character positions. 

ESC D Index - scroll the. current scroll region up one line. WARNING: this behavior is not 

VT100 compatible and is subject to change. 

ESC [/ D CursorBackward -- move the cursor backwards i character positions. 

ESC E Next Line - move the cursor down one line, but if it is at the end of the region, scroll the 

region up (Index). 

ESC [l;c f CursorPosition - Move the cursor to line /, column c. The lines and columns start from the 

upper left, which is (1,1). Specifying zero or leaving an argument blank is equivalent to a 
value of 1. Thus ESC[f alone will "home" the cursor to the upper left 

ESC H Ignored. Used by some terminals to set tab stops. 

ESC[/;cH CursorPosition -- same as ESC f. 

ESC J ClearToEOS - clear from the current cursor position to the end of the AVT. 

ESC [n J Clear -- if the argument is 2, clear the entire AVT. Otherwise, clear to end of AVT. 

ESC K ClcarToEOL -- clear from the cursor to the end of the current line. 

ESC L InscrtLine - insert a line at the cursor position. All the lines below and including the 

current one arc moved down. The bottom line goes away. 

ESC [n L Inscrtl -inc - insert n lines at the cursor position. 

ESC M Rcvcrscfndcx - move the scroll region down one line. The top line in the scroll region 

becomes blank. WARNING: this behavior is not VTIOO compatible and is subject to 
change. 

ESC [/' M DclctcLinc - delete / lines starting from the line that the cursor is on, and move all lines 

below them up. 

ESC P DclctcChar - delete the character at the cursor position, moving all the rest of the 

characters in the line to the left one column* 

ESC [i P DclctcChar - delete / characters, starting from the one under the cursor. 

ESC (® InscrtChar - move all the characters to the right of the cursor to the right one column. A 

space appears at the cursor position. 

ESC [/ @ InscrtChar - Insert / characters at the cursor position. 

ESC[/m If the value of the argument is non-zero, standout mode is turned on, which will mean 

characters appear in reverse video. A zero argument resets to normal video. 

ESC [i;b t Specifics die top and bottom lines of a scroll region. This is used in the Index and 

Rcvcrsclndcx commands. 

ESC < Enter ANSI mode. Currently it is ignored, since AVTs arc always in ANSI mode. 
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ESC ) c Select GO character set Currently it is ignored. 

ESC ( c Select Gl character set. Currently it is ignored. 

The default size of an AVT is 28 lines by 80 columns. This terminal type is just a 28 line VT-100, with a few 
additional escape sequences as described above. On (Stanford) Unix 4.2 systems, this corresponds to die 
terminal type vgts (or vgts28). (Other common AVT sizes arc also supported in the Unix termcap file, 
namely vgts24, vgts48 and vgts54.) For TOPS-20, the command term VT100 will work. On the 
SU-AI waits system, the . t.ty sun 28 80 command can be used for display service. 

46.3. VGTS Message Interface 

This section describes the internal message interface to the VGTS. 

46.3.1. I/O protocol requests 

The following requests of the I/O protocol (see section 33) are supported: 

CREATEJNSTANCE 

Causes a new AVT to be created. The view manager will let the user decide where to put 
the upper left corner of the AVT by changing the cursor and blocking the process until the 
user clicks the mouse. The file instances created arc READABLE, WRITEABLE, 
VARIABLEJiLOCK STREAMS. The first two unspecified fields of the message (if non- 
zero) arc the number of lines and columns in the new AVT. The filename field of the 
message is used as the name of the virtual terminal. Usually this is invoked only by the 
Open Pad ( ) routine described in section 29. 

QUERYJNSTANCE 

Returns the standard values, the same as a Create Instance reply. 

WR1TEJNSTANCE 

Write the bytes to the AVT corresponding to the file instance. Output conversions arc 
performed if the appropriate "Cooking" modes are set 

WRITESHORT INSTANCE 

Same as WRITEJN STANCE 

RKADJNSTANCE 

Blocks until some characters arc entered into the AVT. If there arc any characters already 
in the event queue for this AVT, they arc returned immediately. Note that since the 
instance is VARIABLE_B10CK, un unknown number of characters can be returned, up 
to the blocksizc. 

RELEASEJNSTANCE 

The AVT is deleted, along with any views of the AVT, and storage is reclaimed. 

SET_BREAK_PROCESS 

Hie break process for each instance is the process which will be killed if the view manager 
"Kill Program" command is invoked within die AVT. 

SLTJNSTANCE_OWNER 

Changes die (process) owner of Uic AVT. 

46.3.2. Workstation Agent Requests 

The following request codes (and associated message structures) arc defined in <Vtermagent . h>: 
Query PadRcqucst Returns the cooking mode bits for the AVT, as well as die AVTs width and height. 
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ModifyPadRequest 

The AVTs cooking mode bits and/or size are modified The structure ModiryMsg 
describes the format of this message. 

SwitchTnput The specified AVT is selected for input This is used in the Sal ectPad( ) routine. 

EvcntRcquest The first item from the event queue is returned to the requester. If the event queue is 
empty! the requester is blocked until an event comes in for the given virtual terminal. 

SctBannerRcquestThc specified virtual terminal's banner string is changed. This request code is used by the 
SetVgtBanner routine. 

RedrawRcquest The specified AVT is redrawn. 

LincEditRcquest The data in the message arc treated as line editing commands, rather than simply being 
output to the AVT. Note, however, that the line editor treats most characters as self- 
inserting (sec section 2.5). 

GctRawlO The server and instance ids of the VGTS's own stdio are returned to the requester. The 

new term command uses this code in order to determine what stdio to give the new 
workstation agent 

Die This code requests the VGTS (or other workstation agent) to commit suicide. This is used 

by the new term command, as a temporary kludge only (to circumvent current problems 
with the system^ user number and permission checking policy). 

46.3.3. Other requests 

SEr_DEBUGJvtODE 

Sets (or clears) debugging flags within the VGTS. This code is used by the debugvgts 
command. 

46.4. Internal Organization 

The current VGTS implementation consists (logically) of the following modules ('modules' in this 
description do not necessarily correspond to procedure names or source files): 

• Master Multiplexor. This is the only module which is operating system dependent Upon initialization, 
the appropriate process structure is set up. 'ITic main loop consists of waiting for a message, dispatching 
to the appropriate routine in the other modules, and returning a reply. Synchronization problems are 
avoided by having the data structures accessed only in one process. 

• Terminal emulator. This module interprets a byte stream as if it were an ANSI standard terminal. 
Printable characters arc added to text objects, and control and escape codes arc mapped into the proper 
SDF manipulations. 

• Input handler. There arc various device-dependent input handlers. For example, a single process reads 
die keyboard and sends typed characters to the multiplexor. Another reads die mouse and tracks the 
cursor. 

• SDF manipulator. This module handles requests of applications to create, destroy, and modify 
graphical objects in structured display files. These routines maintain bounding boxes for symbols, and 
call the appropriate redrawing routines when necessary. There is a hash table to locate items given their 
client names. 

• SDF interpreter. These arc the highest level redrawing operations. The structured display files are 
visited recursively, with appropriate clipping for bounding boxes totally outside the area being redrawn. 

• Display operations. These arc the graphical operations called by the SDF interpreter. They are 
generally device independent 
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• Drawing primitives. There is one module which implements device dependent graphics primitives. It is 
conditionally compiled for different graphics devices. 

• Hit detection. The structured display file is visited, but instead of actually drawing the primitives, the 
positions arc checked to match the cursor's position. A list of possibly selected objects (under other 
optional constraints) is returned to the application. 

• View manager. This module allows the user to create, destroy, and modify the screen layout, using the 
mouse. 

• Viewport primitives. These arc the routines which perform the view-changing operations, invoked by 
either an application program or the user through the view manager. 

46.4.1. Executive Interface 

The V-System is intended to be modular, so VGTS could conceivably be used with an executive other than 
the standard one. The VGTS module execs . c handles the Exec Control part of the view manager 
command. It starts up new executives as new processes on the same team, using the CreateExec( ) library 
routine. The Executive calls the functions SetVgtBanner(f He, banner) and 

SetBreakProcess(f He, p1d) as commands arc executed. 

46.4.2. Frame Buffer Interface 

The device-dependent parts of the VGTS currently reside in the files drawl. c and draw2.c. The 

gl, . . . ( ) macros form the interface to the underlying graphics device. These macros are defined in the 

include files gl sunlOO . ti and gl sunl20 . h. (Which include file is used depends upon which version 

of the VGTS is being compiled.) 

46.5. Debugging the VGTS 

The debugvgts command allows the user to obtain a trace of certain events within the VGTS. The 
command syntax is 

debugvgts <debugcode> <VGT #> 

or 
debugvgts trace <VGT#> 

In the first form, the debug code (interpreted as a hexadecimal number) is a disjunction of bit flags taken 
from those defined in the system header file <Vgtp . h>. <VGT #> is the number of a text VGT to which 
debugging output is to be redirected. If this number Is not that of a valid text VGT, then debugging output is 
directed to the VGTS's stdout (the console) instead. Once VGTS debugging has been turned on, it can be 
turned off again using a debug code of 0. A debug code of is also useful for redirecting trace output as 
explained below. 

In die second form of the debugvgts command, the top-level symbol associated with <VGT #> is 
dumped in a symbolic textual form to the current output (as declared in the first form.) This is useful for 
debugging programs Unit use the graphics capabilities of the VG IS as well as debugging the internals, if 
<V(iT #> is positive, then interactive mode is used, and die trace routine pauses after each item listed. If it is 
negative, then the top level symbol of the VGT specified by the absolute value of <VGT #> is dumped 
without pausing. 
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There has been an effort to use a consistent style in V for writing G programs. The style and the uniformity 
it encourages arc motivated by the desire for readability and maintainability of software. Although style is to 
a large extent a matter of individual taste, the following describes some general practices with which most of 
us agree. 

B.1 . General Format 

Recognizing that software is written to be read by other programmers and only incidentally by compilers, 
the general format follows principles established in formatting general English documents. Take a few more 
seconds to make things more readable; it is time well spent 

First, software is written to be printed on standard size (8 by 11) paper. This means avoiding lines longer 
than about 80 columns. In general, there is one statement, or declaration per line. 

As with other documents, judicious use of white space with short lines and blank lines is encouraged. In 
particular, 

1. At least 2 blank lines between individual procedures. 

2. Blank lines surround "large" comments. 

3. Blank lines around any group of statements. 

4. Blank lines around cases of a switch statement 

B.2. Names 

Names arc chosen when possible to indicate their semantics and to read well in use. for example: 
1f (GetOevlce(Etherlnstance) ■« NULL) return N0T.F0UN0; 

Words should be spelled out, not shortened. A good test is to read your code aloud. You should be able to 
communicate it over a telephone easily, without resorting to spelling out abbreviations. 

In addition, character case conventions arc used to improve readability and suggest the scope and type of 
the name. Global variables, procedures, structs. unions, typedefs, and macros all begin with a capital letter, 
and arc logically capitalized thereafter (e.g. MalnHashTable). A global variable is one defined outside a 
procedure, even though it may not be exported from the (lie. or an external variable. The motivation for 
treating macros in this way is thai they may then be changed to procedure calls without renaming. 

Manifest constants cither follow the above convention (since they arc essentially macros with no 
parameters) or else arc fully capitalized with use of the underscore to separate components of the name. E.g. 
WRITEJNSTANCE 

Local variables begin with a lower-case letter, but arc cither logically capitalized thereafter (e.g. bl tW1 dth, 
power, maxSuroOf Squares) or else totally lower case. Fields within structures or unions arc treated in this 
manner also. 

Local variables of limited scope arc often declared as register, if they arc used very often inside inner loops. 
It is not only more efficient but usually more readable, to put a pointer to an array of complicated structures 



Appendices 7 June 1986 



B-2 C Programming Style 

(a common occurrence in object-oriented programming) into a register variable with a short name. For 
example, 

register struct Descriptor *p - DescMptorTable+objectlndex; 
p->count ■ 0; 
Initial 1re(p->start); 
p->usage ■ p->default; 
p->length ■ p->end - p->start; 

instead of the inefficient and cluttered: 

Descr1ptorTable[objectIndex]. count - 0; 
In itialize(DescriptorTable[object Index], start); 

DescriptorTablefobject Index]. usage ■ Descr1ptorTable[objectIndex]. default; 
Oescr1ptorTable[objectIndex]. length ■ Descr1ptorTable[objectIndex].end 
- Descr 1 ptor Tab le[obj act Index]. start; 

B. 3. Comments 

There are generally two types of comments: block-style comments, and on-the-line comments or remarks. 
Mulii-linc. block-style comments have the /*and */ appearing on lines by themselves, and the body of the 
comment starting with a properly aligned *. The comment should usually be surrounded by blank lines as 
well. Thus it is easy to add/delete first and last lines, and it is easier to detect the common error of omitting 
the */ and thus including all code up to and including the next V in a comment 

/•'■'" 

* this 1s the first line of a mult1-11ne comment, 

* this 1s another line 

* the last line of text 
*/ 

On-line comments or remarks arc used to detail declarations, to explain single lines of code, and for brief 
(i.e. one line) block-style descriptive comments. 

Procedures arc preceded by block-style comments, explaining their (abstract) function in terms of their 
parameters, results, and side effects. Note that the parameter declarations arc indented, not flushed left 

SystemCode EnetCheckRequest(req) 
register IoRequest *req; 

{ 

/• 

* Check that the read or write request has a legitimate buffer, etc. 
•/ 
register unsigned count; 
register SystemCode r; 

/• Check length •/ 
count ■ req->bytecount; 
1f (count <- IO_MSG_BUFFER) return OK; 

req->bytecount ■ 0; /• To be left zero 1f a check falls •/ 
If (count > ENET MAX_PACKET) 

{ 

r - BAD_BYTE_COUNT; 



} 
else 

{ 



/• 

* Make sure data pointer 1s valid. 

* Check that on a word boundary and not 1n the kernel area. 
•/ 
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If ((ICheckllserPo1nter(req->bufferPo1nter)) || 

(Activ8->team->teamSpace.s1ze < (req->bufferPo1nter ■► count)) || 
((1nt) req->bufferPo1nter) & 1) 

{ 

r - BAD BUFFER; 

} 

8lS» 
{ 

req->bytecount ■ count; 
r - OK; 
} 
} 
return r; 

} * 

B.4. Indenting 

The above example shows many of the indenting rules. Braces ( "{" and "}" ) appear alone on a line, and 
are indented two spaces from the statement they arc to contain. The body is indented two more spaces from 
the braces (for a total of four spaces), el se's and else it's line up with their dominating 1f statement (to 
avoid marching off to the right, and to reflect the semantics of the statement). 

1f ((x - y) « 0) 

{ 
flag ■ 1; 
pr1ntf(" the value was zero "); 

} 
else 1f (y ■• 1) 

{ 

switch (today) 

{ 

case Thursday: 
flag - 2; 
ThursdayAct1on(); 
break; 

case Friday: 
flag ■ 3; 
Fr1dayAct1on(); 
break; 

default: 

0therDayAct1on(); 

} 
> 
else 

pr1ntf(" y had the wrong value "); 

B.5. File Contents 

File contents arc arranged as follows. 

1. Initial descriptive comment (sec example below), containing a brief descriptive abstract of the contents. 
Some programmers also add a list of all defined procedures in their defined order, or alphabetically. 

2. Included files (avoid the use of absolute path names) 

3. External definitions (imports and exports) 

4. External and forward function declarations 

5. Constant declarations 

6. Macro definitions 
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7. Type definitions 

8. global variable declarations (use static declarations whenever possible, and group variables with the 
functions that use them) 

9. procedure and function definitions 
Here is the beginning of a file as an example. 

/* 

* Distributed V Kernel - Copyright (c) 1982 by David CheHton. Willy Zwaenepoel 

* 

* Kernel Ethernet driver 
•/ 

#1nclude ". ./. ./Hbc/include/Vethernet.h" 

#include "Interrupt. h" 

^include "ethernet.h" 

^include "1kc.h" 

#1nc1ude "../ml/dm.h" 

/• Imports •/ 
extern Process *Map_p1d(); 
extern SystemCode NotSupported(); 
extern Oevicelnstance *6etDevice(); 

/• Exports •/ 
extern SystemCode EnetCreate(); 
extern SystemCode EnetRead(); 
extern SystemCode EnetWr1te(); 
extern SystemCode EnetQueryj); 
extern SystemCode EnetCheckRequest(); 
extern SystemCode EnetReadPacket(); 
extern SystemCode EnetPowerup(); 



unsigned char EnetHostNumber; 



Instanceld 

1nt 

short 

1nt 

1nt 

int 

1nt 

int 

int 

Int 

char 

kPacket 



" /• physical ethernet address •/ 

/* Instance 1d for Ethernet •/ 

/• addresses to listen for */ 

/• Current status settings •/ 

/* FIFO was emptied by last read */ 

/• Number of collision errors •/ 

/* Queue overflow errors */ 

/* Packets with bad CRCs */ 

/* Receiver out of sync */ 

/* Transmitter timeouts •/ 

EnetValldPackets - 0; 

kPacketArea[WORDSJ>ER_.PACKET*BYTES_PERJrfORD+20]; 

/* Save area for kernel packets */ 

*kPacketSave - (kPacket *) kPacketArea; 

/* Pointer to kernel packet area */ 



Ethernetlnstance; 
EnetRecelveMask; 
EnetStatus; 
EnetFIFOempty; 
EnetColHslons - 0; 
EnetOverflows ■ 0; 
EnetCRCerrors ■ 0; 
EnetSyncErrors - 0; 
EnetTimeouts ■ 0; 



/* Macro expansion to Interrupt-lnvoked C call to Ethernetinterrupt 
CallHandler(Enetlnterrupt) 



B.6. Parentheses 

For function calls, the parentheses "belong to" the call, so there is no space between function name and 
open parentheses. (There may be some inside the parentheses to make the argument list look nice.) When 
parentheses enclose the expression for a statement (1f, for, etc.), the parentheses may be treated as 
belonging to the expression, so there is a space between the keyword and the parenthesized expression. This 
also clearly distinguishes the statement from a function call. 
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1f (FuncA()) 

{ 

FuncB((a ■ b) ■■» 0); 
return Nil ; 

> 
else 

{ 

FuncC(a, b, c); 
return ToSender; 

} 

Alternatively, parentheses may be treated as belonging to the statement (since they are syntactically required 
by the statement) so there is no space between the keyword and the expression. 

1f( (bytes ■ req->bytecount) <■ IO_MSG_BUFFER ) 

buffer » (char *) req->shortbuffer; 
else 

return req->bufferPo1nter; 

Note that parentheses are not syntactically required around the expression of a return statement 
Nevertheless, such parentheses may still be included, if so desired. 

Note that spaces are used to separate operators from operands for clarity and may be selectively omitted to 
suggest precedence in evaluation. 

B.7. Messages 

Although V is a message-based system, most services are available by calling standard routines, so 
programming at the "message level" is rarely necessary or desirable. However, the programming of new 
servers and the non-standard use of services or the use of messages within a program require message-level 
programming. The following conventions have been followed in V. 

Space to send or receive a message is declared of type Message (an array) or MsgStruct (a structure with 
appropriate fields), as defined in <Vcnviron.h>. Standard message formats, as defined in the V header files, 
declare each message format to be a new data type. Each message format contains enough padding to fill it 
out to the fixed message size used by the kernel. Where the same space is used for messages of multiple 
formats (for example, both request and reply messages), access to the space for the message can be made by 
casting a pointer to the space to be of the type of the message format requires. 'Hie following illustrates this 
style. 

Read(fad, buffer, bytes) 
File *fad; 
char *buffer; 
1nt bytes; 
/• 

* Read the specified number of bytes Into the buffer from the 

* file Instance specified by fad. The number of bytes read 1s 



returned. 



{ 



Message msg; 

register IoRequest "request ■ (IoRequest *) msg; 

register IoReply *reply ■ (IoReply •) msg; 

register unsigned r, count; 

register char *buf; 

for(;;) 

{ 

request->requestcode - READ__INSTANCIi; 
request->f1le1d ■ fad->f1le1d; 
request->bufferPo1nter • buffer; 
roquest->bytecount ■ bytes; 
request->b1ocknumber ■ fad->block; 
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if (Send(request, fad->f11eserver) »■ 0) 

{ 

fad->lastexcept1on - NONEXISTENT_PROCESS; 

return 0; 

} 
1f ((r ■ rep1y->replycode) !■ RETRY) break; 

} 

fadr>lastexcept1on - r; 
count « reply->bytecount; 

if (count <- IO_MSG_BUFFER) 

{ 

buf • (char •) request->shortbuffer; 

for (r ■ 0; r < count: ++r) *buffer++ ■ *buf++; 

} 
return count; 

} 
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Installation Notes 



This document describes the installation and maintenance of the V-Systcm software. The reader should be 
familiar with the V-System as documented in the V-System manuals, and with the Unix system used for 
development 

C.1 . V-System Distribution Tapes 

The software is distributed on a 1600 bpi Unix tar format tape. Licensing information and tapes can be 
obtained from: 

Office of Technology Licensing 

Suite 250 

350 Cambridge Ave. 

Palo Alto, CA 94306 

(415)723-0651 

All the software is under copyright protection, so you must get a license from Stanford to have this software. 
New versions of the software may be released from time to time. . Send comments on the software and 
documentation to the Arpanet address vbugs8pescadlero.stanford.edu. Please report any bugs you 
find, or improvements you make. 

The Mill V distribution consists of two tapes, die binary distribution (or binary tape), and the source 
distribution (or source tape) which has the sources to the V system itself. V6 . combines both of these on a 
single tape, with the "logical binary tape" first The combined space requirement for V6.0 is approximately 67 
megabytes. 

Note: This V distribution runs on Cadlinc and SUN MicroSystems workstations with 68000s (SUN-ls), 
SMI workstations with 68010s and 68020s (models 2/{50,10O,120,170} & 3/{75,160}), and ni:c MicroVAX-H 
workstations with and without framebuffcrs. Kthcrnct drivers arc provided for the 3COM and Kxcclan lOmcg 
boards, the Intel 82586 LAN chip (found in SMI 2/50 and 3/75 models), the SMI 3 meg board, and the 
DEQNA. There is presently no driver for the SMI Multibus 10 Mbit Kthcrnct interface or for the AMD 7990 
chip found in the Sun-3/50. The vax server host side must be running 4.2 or 4.3 BSD. 

C.2. Binary Distribution Tape 

The binary tape contains 3 tar (Unix tape-archive format) files: 

enct: Hie files required to install our clhcrnct packet filter code in a Vax/Unix 4.2 kernel. The 
installation.doc and enctdoc files that arc part of this tape file describe how to install die driver and 
how it works, respectively. This code should be included in die official 4.3BSD release. 

unix: The binaries and some sources for Unix support programs and servers used with V. 

usr.V: Files used by workstations running the V-systcm. 

• V binary images for kernel, servers and programs. 

• V libraries for C programs in Unix tar format. 
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• V header files for C programs, defining standard manifest constants and structures. 

• Miscellaneous configuration and documentation files. 

The binary tape is structured to be loaded into a single subtree of a Unix file system. Make a subdirectory 
on a partition with at least 65 megabytes free. We suggest calling it V6.0. Change to the V6.0 directory, make 
another subdirectory called enet and change to it. Extract the packet filter from the tape. Change to V6.0 and 
run tar x repeatedly to extract the remaining files from the tape. (Due to extra cnd-of-filcs, you may get a 
"0 blocks read" message between files.) 

Several programs expect to find files in certain directories. Run the VI Ink shell script to link the 
distribution into the file structure. 

Add the termcap.vgts entries to /etc/termcap. 

C.2.1 . V Subdirectories 

There are several subdirectories of interest under the "V" subdirectory in the installation directory: 

bin Binaries of the V-systcm commands and servers. These arc the programs that run under V 

on the workstations. 

boot This directory contains standalone programs (programs that do not run under the V kernel) 

such as Vload (the V-Systcm bootstrap), and the netwatch family of network 
monitoring programs, plus initial teams to run under the V kernel. The subdirectory 
"Vkerncl" contains various V kernel configurations. 

config Workstation configuration files. One config file exists per workstation. These files arc used 

by the ndserver to determine which version of Vload to download, by Vload to 
determine which kernel image to load, and by the intcrnctscrver to- determine the 
workstation's IP address. 

fonts Type fonts used by the VGTS and other V-Systcm programs. 

include The include ( . h) files. Most V-Systcm include files start with an upper case "V". 

lib The V-Systcm libraries. The main run-time library is libV.a Other major libraries are 

HbsunlOOVgts.a for the SUN-1 frame buffer and libsunl20Vgts.a for the SUN-2 
framebuffer, raw character I/O for various hardware configurations, and lowlcvel V ike 
libraries for standalone programs. There is also a library lor each of the different servers, 
eg. lib VintcrncLa contains the Internet server, providing primarily IP/TCP service. 

misc Other random files. 

run Various files that are used by programs for runtime support. 

C.2.2. Network File Service and Bootloading 

The next step is to provide network file service and bootloading service. 

1. Provide access to the lUhcmct on your VAX/UNIX system (the only configuration fully supported by 
the distribution tape). 

2. Modify the configuration files, under V/config to indicate the desired configuration and network 
addresses of your workstations. 

3. Install and initiate the execution of the Vscrvcr and ndserver on the Vax. 
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C.2.2.1 . Ethernet Filter Code 

This code must be added to the Unix kernel, if not already present It allows a user program to open the 
Ethernet directly for reading and writing as a special device file. The user program can then specify by a 
"filter" which packets it wants to receive. See enct/lnstallation.doc for installation information and 
enct/cnctdoc for a brief description of the code. Note that 4.2 BSD docs not currently provide this 
functionality. However, a group at Stanford has convinced the weenies at Berkeley to include this driver as a 
standard part of Berkeley Unix, starting with the 4.3 release. Make sure the maximum packet size (MTU) is 
large enough to fit all the data bytes in a kernel packet plus the header, currently about 1200 bytes. The V8 . 
release packet filter is incompatible with previous packet filter releases. 

In addition, the network driver files in_proto.c and ipjnputx should be replaced in /usr/sre/sys/netinet. 
This adds the lPPROTO.ND protocol family (used by SMI boot proms) to the kernel. 

C.2.2.2. Ethernet multicast reception 

Important: Make sure that your Unix ethernet driver is set up to receive all multicast packets. By default 
most drivers do not listen to these packets. Multicast is now a fundamental part of the V intcrkcrncl protocol. 

C.2.2,3. DEC Deuna 

Change the initialization line in /usr/src/sys/vax1f /1f de . c to include the multicast enable bit* 

#1fdef STANFORD 

/* receive all multicast packets to keep V people happy */ 
ds->ds«-pcbb.pcbb2 * M0D*-TPAD|M0D«-HDX|M0D*-ENAL; 

#else 

ds->ds«-pcbb.pcbb2 « M0D«-TPAD|M0D<-HDX; 

tfendif STANFORD 

C.2.2.4. Interlan 1010a 

Before setting the Interlan board online send an additional command to enable reception of all multicast 
packets (in /usp/src/sys/vax1f/-ffj.l.c): 
#ifdef STANFORD 
/• 

* For V people: receive all multicast packets 
*/ 

addr->1l*-csr ■ ILOALLMC; 

while ((addr->1l«-csr & IL«-CD0NE) « 0) 

#endif Stanford' 
/* 

* Set board online. 

* Hang receive buffer and start any pending 

* writes by faking a transmit complete. 

* Receive bcr is not a muliple of 4 so buffer 

* chaining can't happen. 
•/ 

C.2.2.5. Configuration Files 

The "con fig" files provide information about individual network nodes or workstations. If a node has 
Kthcrnct address AAAAAAAAAAAA (in hex) then its configuration file should be 
eonfig/C.AAAAAAAAAAAA. In general, C* files describe a network node, G.* files describe routing to be 
used by a gateway and S.* files arc scripts for servers to execute on initialization. Config files contain 
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information fields of the form "name: value". Several cxapmlcs are included in V/conf 1g. See chapter 19 
for a full description of the keywords and their appropriate values. 

The fields needed for booting are: 

name Name to be used as a user-specified designation of network node. 

bootfile Which version of VI oad to download. Sun-2/50s must have this field set to Vload50.d. It 

defaults to VloadlO.d for Suns and Vload.vax for micro Vaxen. 

alt-ether-addr Sun-2 workstations that have 3COM ethcrnet interfaces use the SMI address 

(0800.2001. xxxx) for booting and the 3COM address (0260.8c00.xxxx) when running the 
V-System. To configure such a workstation, name the config file after its 3COM address 
and put the SMI address in the alt-ether-addr field. SMI workstations generally print their 
SMI-assigned cthernct address on the screen during powerup. You can determine your 
workstation's 3COM address by running the following program under SMI Unix: 
^include <sys/f 11e.h> 



ma1n() 
{ 



1nt fd, 1; 

unsigned char addr[6]; 

fd ■ open("/dev/mbmem", 0«-RDONLY» 0); 

1seek(fd, OxE0400, 0); 

for (1-0; 1<6; 1++) 

read(fd, &addr[1], 1); 

pr1ntf( w %02x%02x.%02x%02x.%02x%02x\n , \ 
addr[0], addr[l], addr[2], 
addr[3], addr[4], addr[5]); 



C.2.2.6. Initiation of V Servers on Unix 

The directory unix/ctc contains the Unix server programs needed to boot diskless workstations and serve 
remote sessions. This directory is symbolically linked to /etc/V. 

The Vscrvcr uses the file V/run/Vhosttab to map from hostnames to V logical host ids. Since this file is 
installation dependent you'll have to generate it by editing the SKRVKRIIOSTS variable in (source) 
V/scrvcrs/unix/buildfilc, run buildmakc, Uicn make install. 

The line "sh /ctc/V/rc" should be added to 7etc/rc. local to fire up these server programs whenever 
the system is booted. (The "re" file also provides a reasonable description of how to hand start these servers.) 
Note: the Vscrvcr expects to be run as root, so that it can fork "sessions" that sctuid to the appropriate user. ' 

There must be at least one public Vscrvcr running in any given local network. A Vscrvcr is made public by 
starting it with the -p flag. Sec the Unix Server section of the manual for further information. 

C.2.3. V Authentication Files 

V8 . requires two files for authentication: the Vpassword file, which is used by the Vauthcntication server 
to authenticate (log in) users, and the Vuscrcorrcspondcncc file, which maps V user numbers to Unix user 
names. For a complete description sec chapter 35, Authentication and the Authentication Server. The section 
35.5 explains the use and needs of the files involved in V audicntication. 

Two awk scripts arc provided to generate the Vuscrcorrcspondcncc and Vpassword files from the Unix 
/ctc/passwd file, llicsc scripts make each V user's V password die same as their password under Unix, and 
makes their V home dirccotry on the correct Unix host. These scripts arc aimed at sites which have only one 
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Unix host providing V file service. Section C.2.3.4 explains what to do if you have more than one such Unix 
host 

C.2.3.1 . Creating the Vpassword File 

Follow the directions in /etc/V/Vpassword . awk, then create a rough password file by executing 
awk -f /etc/V/Vpassword.awk < /etc/passwd > /tmp/rough 

Edit /tmp/rough to remove password entries for such Unix users as root, uucp, etc. Copy /tmp/rough to 
Aisr/V/misc/Vpassword. 

C.2.3.2. Creating the Vusercorrespondence File 

Follow the directions in /etc/V/Vusercor r . awk, then create a rough correspondence file by executing 
awk -f /etc/V/Vusercorr.awk < /etc/passwd > /tmp/rough 

Edit /tmp/rough to remove the same extraneous entries deleted from the password file. Copy /tmp/rough to 
/ctc/V/Vusercorrcspondcnce. 

C.2.3.3. The Unknown User and the V administrator 

A workstation which has nobody logged in is authenticated to a special unknown user. We assume that you 
may want people to be able to run V programs (such as telnet and nctwatch) without logging in. To do so, 
create an account called "Vunknown" on your unix system, make its home /tmp and give it minimal 
privileges. In addition you should create "Vadmin" an account for the administration of V system files and 
chown /usr/V/misc/Vpassword to that user. 

C.2.3.4. V Authentication and Multiple Vservers 

If you have more than one machine serving V, you must create a single password file that contains entries 
for the users from all of the machines. To do this first create a Vpassword file on each offsetting the V user 
numbers so that there is no overlap between machines. Then form a rough master password file by merging 
all of them together on the master password site. Massage the rough master by editing out duplicate entries, 
keeping the entries that correspond to each users "home" machine. Sorting the rough password file before 
duplicate deletion makes this chore much easier. 

It is a bit more difficult to automatically generate individual correspondence files when building a merged 
Vpassword file. 'ITiis is because there may be little relation between a given user's V user number and the 
user's Unix uids on multiple Unix hosts. We suggest starting with a minimal correspondence tabic on each 
machine and having users run addcorr the first time they log in to the V-Systcm. A minimal file sufficient 
to boot and test the system is as follows: 

Vadmin 

1 Vadmin 

2 Vunknown 

C.2.4. The Boot Sequence 

This section explains what happens during the bootstrap process. Sec chapter 16 for a detailed description 
of workstation bix>t commands. The boot process consists of three steps: loading Vload, the V-systcm 
b(K)tstrap, loading the kernel and first team, and initializing the system (which may include downloading 
more programs such as the v gts). 

Vload is downloaded over the network using the diskless booting protocol contained in the workstation's 
proms. There arc many brands of workstations, and even more boot protocols. Once running, Vload locates 
and connects to a "public" Vscrvcr to load the appropriate kernel and first team. After Vload has been 
loaded, all subsequent network file I/O is performed through a V server using V intcrkcrncl protocols. 
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C.2.4.1.SUN-1 

Owners of Sun-Is are pretty much on their own. At Stanford we use our own proms which boot using PUP 
EFrP. You may have another protocol, or none at all. We suggest upgrading to a Sun-2. 

C.2.4.2.SUN-2 

Booting SUN-2 workstations with the ND protocol requires a running ndserver. The actual boot 
sequence is as follows. When an SMI workstation boots, if it contains no disk interface, it attempts to boot 
over the Ethernet. This is done using the "ND" boot protocol which asks for the first 18 512-byte blocks of a 
virtual disk. (Several of these blocks are thrown away. The boot program must be less than OxlEOO bytes of 
text and initialized data). The ND server "intercepts" these requests and replies with VI oad. 

In general, the ndserver is a modest "hack" to allow one to run V on SMI SUN workstations without 
modifying the PROM monitor as it comes from the manufacturer. If a Sun is to run SMI Unix the field 
"bootino" should be placed in the workstation's .config file to prevent the ndserver from downloading 
VI oad. 

C.2.4.3.SUN-3 

Sun-3 workstations require running rarpd and tf tpd servers. A Sun-3 boots using IP RARP (reverse 
address resolution protocol) to determine its IP address, then uses TFTP (trivial file transfer protocol) to 
download a bootstrap program. 

The rarpd uses a simple database file, rarpdb.<pseudo-nct>, to map physical ethcrnct addresses to IP 
addresses. Edit the example file to include the Sun-3s that will be running V6.0. Make sure that the <pseudo- 
net> extension matches the enct device corresponding to the 10 meg interface that the workstations arc on. 
Typically this is "cnet" or "cneta". 

Once the Sun-3 knows its IP address it uses TFTP to download a file named by its hexadecimal IP address. 
For instance, if the rarpd responds with "36.8.1.3", the workstation will attempt to load a file named 
"24080103". This file should be linked to VI oad3+1 e . d, the Sun-3 version of VI oad. These files (including 
a copy of Vload3+1e . d) should be placed in your tftp daemon's home directory. The tf tpd distributed in 
4.2BSD was buggy. We've included a patched version with V6.0, along with a rarp daemon. Remember to 
start the rarp and tftp daemons from /ctc/rc.local. 

Note: 'ITic Sun-3 boot process doesn't involve a workstation's configuration file until after VI oad is 
running, so neither the 'bootfile' nor the 'boot' config file fields affects booting. To run Sun Unix prevent the 
tftpd from downloading VI oad by removing the file linked to VI oad3+1 e . d. 

C.2.4.4. MicroVAX 

Booting MicroVAX workstations requires the mvaxbootserver to be running on a Unix host The 
mvaxbootserver services MicroVAX network boot requests just as the ndserver responds to SMI ND 
requests. A "boot:no" entry in the workstation's config file will prevent the mvaxbootserver from 
responding to boot requests. 

C.2.5. Debugging Suggestions 

If the system fails to boot after following the above sequence, it is suggested that you try booting a 
"standalone" program like netwatch to check the initial portion of boot sequence and also (assuming you 
have multiple workstations), monitor the network activity when you try a full system boot See the 
"Standalone" chapter of the reference manual (chapter 16) for details on how to load and use standalone 
programs. Section 16.2 gives an overview of how to use the netwatch family of programs. In general, the 
netwatch family of programs arc very useful for debugging network problems. They keep a record of 
network packets which can be written to a log file. Please include such a log file in bug reports that relate to 
the network. 
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If the workstation fails to load a standalone program, check that your cthcrnct connection is working 
correctly. This is easiest if you have other means of monitoring Ethernet activity. You should also check that 
the ndserver or mvaxbootserver is properly instructed to respond to requests from the workstation's 
host address by having the correct config files present The ndserver or mvaxbootserver can be 
executed with the "d" flag to put it into debugging mode. This should give a clear indication as to whether or 
not it is receiving the workstation boot request packets and what it is doing in response to the packets it 
receives. 

Assuming you can load standalone programs, you should be able to load Vload. The error codes 
generated by Vload (e.g. "C017") can be decoded by looking the the header file 
V/1nclude/m1/Ver\v1ron.h. Besides using netwatch to monitor network activity, one can run the 
Vserver in debug mode. Option "A" gives a verbose account of the Vservers's activities. Sec chapter 43 for 
the details of other debugging options. 

C.3. Source Distribution Tape 

The source distribution tape contains the V-Systcm sources. Unless one is modifying the standard software 
or recompiling for some reason, there should be no reason to keep these sources on-line. 

The procedure for extracting the files of the source tape is identical to that used with the binary distribution 
tape. Warning: Do not extract the source tape into the same directory as the binary tape. Some 
subdirectories have identical names. At Stanford, we keep V sources under /V. 

C.3.1 . Structure of the V Sources 

The V source directories arc structured by function and by machine dependency. For convenience each 
division is in a separate tar file. The major functional divisions are: 

cmds Standard command programs. A subdirectory for each command program (with some 

exceptions that we plan to eliminate). 

kernel V Kernel sources. The machine-independent source is under mi, 680X0 source under 

m68k, Microvax source under vax, and configuration-specific files under the other 
subdirectories. For example, sun2+cc configures the kernel for the SUN-2 with a 3COM 
Ethernet interface. 

libc Standard C run-time library for V. Subdirectories for different functional parts of the 

library. Machine-specific directories occur at various levels if there arc machine-specific 
files. 

servers Server programs. A subdirectory for each separate server. The two Unix server programs 

ndserver and Vserver arc here, though they don't run under V. 

standalone Standalone programs. A subdirectory for each separate program. 

fonts: Sources for some of the fonts used in the V-Systcm. 

doc: The V6.0 manual in Scribe format 

C.3.2. Recompiling V Sources 

Many of the V-Systcm makefiles invoke cc68 to compile and link. Be sure you have the latest version 
(included on the tape) of ccB8, with the -V option. 

Edit the shell script under V/net Install to perform the appropriate installation procedure for your 
system. Some possibilities arc for it to copy the binaries to other V hosts on your network (thus automating 
the installation and causing changes to take network-wide effect immediately), copy binaries to hosts in the 
local V-domain only, or copy to the local host only (a good choice if you have only one host running a Vserver 
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or update local hosts with regular rdists). It's important to keep all of the V binary directories synchronized 
within a domain since binaries arc often served by the first Vserver to answer a request. This and a few 
other shell scripts arc assumed to bejn the search path by the V-System makefiles. These sources arc in 
V/tool s and should have been installed into some directory in the search path by VI 1 nk before making the 
rest of the system. Each directory contains a file called bulldf 1le which is processed by the build 
program, an enhanced version of make. The sources to bu1 1 d are included. 

The following describes the steps (and order) to completely remake the V-Systcm binaries (and libraries). 

Change directory to V/I1bc and do a build 1nstall-1ncludes. This should copy the V-Systcm 
specific include files into /usr/V/1nclude. Then do a build and then build Install under this 
directory. This should result in 1 1bV. a being copied into /usr/V/1 1b. 

Next, change to the V/standal one directory. This directory is for bootstrapping and loading utilities. 

Next, change to /V/kernel. There is a subdirectory corresponding to each of the hardware combinations 
currently supported by the V-Systcm. cd to the directory corresponding to your hardware configuration, then 
do a build followed by a build Install to compile the kernel and put the binary into 
V/boot/Vkernel. For instance, V/kernel /sun2+ec and V/kernel /sunl+en correspond to the 
configurations "sun2 cpu with 3COM cthcrnct" and "sun! (old sun, cadlinc etc.) with sun 3meg cthcrnct". 
You may have to create a new subdirectory and edit the buildfilc to configure the kernel for your I/O devices. 

Next change directory to /V/servers, and do a build followed by a bu1 Id Instal 1. 

Next, change directory to /V/cmds and again do a build followed by a build Install to compile all 
the commands. This takes a while, and uses the include files, libraries, and servers. 

Do the same for /V/conf1g (after making some config files for your workstations) and 
/V/standalone. 

C.3.3. Source Distribution Summary 

The source tape provides all the files required to regenerate the binary distribution tape files (we believe). 
Any omissions were unintentional or forced upon us by lawyers. 
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List of Library Functions defined in libc 



ASSERT mem/mi/malIoc.c 

AcquircSpinLock locking/mi/spinlock.c 

AddUser auth/mi/adduscrx 

AllocFonit graphics/mi/allocraster.c 

AllocRaster graphics/mi/allocraster.c 

ArbLoadProgram excc/mi/arbloadprog.c 

Attention drivcrs/m68k/cnet50.c 

Authenticate auth/mi/authenticatex 

AwaitKcrnelPacket drivers/m68k/cnet3.c 

AwaitingReply ipc/mi/awaitingrepl.c 

BlksInFile io/mi/blksinfile.c 

BlockPosition io/mi/blkposition.c 

BlockSize io/mi/blocksize.c 

BoundingBox graph ics/mi/rastcrbbox.c 

BufFerEmpty io/mi/bufTcrempty.c 

BufTerModificd io/mi/scck.c 

BufFcrValid io/mi/fillbuffcr.c 

BytcPositlon io/mi/bytcposition.c 

BytcSwapLongCopy • mcm/mi/swablongl.c 

BytcSwapLonglnPlace mcm/mi/swablong2.c 

BytcSwapShortCopy mem/mi/swabshorte 

BytcSwapShortlnPlacc mem/mi/swabshorte 

ChangcDircctory io/mi/chdir.c 

ChangcTcamPriority cxcc/mi/changctcampr.c 

ChcckKxccs cxccscrvcr/mi/chcckcxccsx 

ClcarEof io/mi/clcarcof.c 

Close io/mi/closc.c 

ColToRowRastcr graphics/m68k/columnordcr.c 

CompB graphics/vax/rastcrop.c 

CompImmedB graph ics/vax/rastcrop.c 

CompImmcdL graph ics/vax/rastcrop.c 

CompImmcdW graph ics/vax/rastcrop.c 

CompImmcdX graph ics/vax/rastcrop.c 

Complncir graph ics/vax/rastcrop.c 

CompI graph ics/vax/rastcrop.c 

CompI.it graphics/vax/rastcrop.c 

CompLitL graphics/vax/rastcrop.c 

Compl-oad graphics/vax/nistcrop.c 

CompOp graphics/vax/rastcrop.c 

CompRcg graph ics/vax/rastcrop.c 

CompW graphics/vax/rastcrop.c 

Copy Downwards mcm/mi/bcopy.c 

CopyHcld auth/mi/atoar.c 

CopyMsg drivcrs/ni68k/cnct3com.c 

CrcatcDuplcxInstance io/mi/crtdupinstc 
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CreateExcc 

CreatcGroup 

Createlnstance 

CrcatePipelnstance 

Dcbug_BDL . . . 

Dcbug_Dcqna 

Dcfaul tRootMcssage 

DcfaultSelcctionRec 

DclcteExec 

DcleteUser .... 

Destroy AuthRcc 

DiscardDataPacket 

EnetFlushRccciver 

Enctlnterrupt 

EnetPowerup . . . 

EnetRcset 

Eof 

EqString 

ErrorString 

ExecProgram . . . 

Execl 

Exccv 

FileException 

Fileld 

FileServer . . . . 

FileType 

FillBuffcr 

FindMatch 

FindMatchingProgs 

Flush 

Flush Buffer 

Force Exception 

ForccSend 

Forwarder 

Frcc/cHost . . . . 

FullUscrName 

GctFakcPid 

GctFont 

GctFontEntry 

GctFormatString . . 

GctKcrnclPid 

GctM orcM allocSpace 

GctNumbcrOfParams 

GetNumbcrolParams 

GciParams . . . . 

GctProccssorType 

GctSigncdl 

GctSigncd2 

GctSigned3 

GctSigncd4 . . . . 

GctStringParams 

GctTcamPriority 

GctUnsigncdl 

GctUnsigncd2 



exccscrver/mi/createcxcc.c 

ipc/mi/creategroup.c 

io/mi/createinstc 

io/mi/creatcpipe.c 

drivcrs/vax/deqna.c 

drivcrs/vax/deqna.c 

excc/mi/cxccprogram.c 

excc/mi/dcfaultsclrec.c 

exccserver/mi/deleteexec.c 

auth/mi/deleteuser.c 

auth/mi/destroyar.c • 

drivers/m68k/cnet3.c 

drivers/m68k/enet3.c 

drivcrs/m68k/enet50.c 

drivers/m68k/enet3x 

drivcrs/vax/deqna.c 

io/mi/eof.c 

graphics/mi/gctfontc 

exccptions/mi/error.c 

excc/mi/exccprogram.c 

excc/mi/system.c .. 

exec/mi/systemx 

io/mi/filcexceptc 

io/mi/filcidx 

io/mi/filcscrver.c 

io/mi/filctypc.c 

io/mi/fillbufferx 

excc/mi/lookup.c 

excc/mi/lookup.c 

io/mi/flush.c 

io/mi/flushburTcr.c 

cxccptions/mi/forcccxccpt.c 

cxccptions/mi/forccscnd.c 

ipc/mi/forwardcr.c 

cxceptioiis/mi/frcc/.chost.c 

autii/mi/fulluscrnamc.c 

drivcrs/m68k/cncG.c 

graph ics/mi/gctfontc 

graphics/mi/gctfontc 

cxccptions/m68k/stdcxccptc 

cxcc/mi/kcrnclpid.c 

mcm/mi/mallocaux.c 

cxccptions/m68k/printstack.c 

cxccplions/m68k/stdcxccpt.c 

except ions/m68k/stdcxccptc 

cxccptions/vax/stdcxccpLc 

io/mi/getbigcndian.c 

io/mi/gctbigcndian.c 

io/mi/gctbigcndian.c 

io/mi/gctbigcndian.c 

cxccptions/m68k/stdcxccptc 

cxcc/mi/gctteampr.c 

io/mi/gctbigcndian.c 

io/mi/gctbigcndian.c 
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GctUnsignecl3 . 

GctUnsigncd4 

GivcToMalloc 

INCR 

InstructionFctch 

Interactive . . 

IntcrruptBoard 

JoinGroup 

KillPrograra 

LeavcGroup 

Listl28 . . . 



Listl6 

Lisa 

List256 

List32 

List4 ..... 

List64 

ListS 

LoadFileRegion 

LoadGcncricFont 

LoadPrograna . . 

LoadTcam FromFile 

LoadXmitDcscriptor 

LogOutExecs 

LookupFont 

MASKOP . . . 

MapTcamName 

MapUID 

MapUserNaime 

ModifyUser 

MovcFrom . . . 

MoveTo 

NcwRaster 

Offset 

Open 

Open Duplex . . 

Open File 

Opcnlp 

OpcnProgFile 

OpcnStr 

OpcnTcp . . . 

Parse Line 

Password 

PaltcrnOp 

Prinilvrror 

PrintFilc .... 

Prints tackDump 

PutSigncdl 

PutSigncd2. 

PutSigncd3 

PutSigncd4 . . . 

PutUnsignccll 

PutUnsigncd2 

PutUnsigncd3 



io/mi/gctbigendian.c 

io/mi/gctbigcndian.c 

mem/mi/malloc.c 

graphics/vax/rasterop.c 

exceptions/m68k/stdexccptc 

io/mi/intcractive.c 

drivcrs/m68k/enetxln.c 

ipc/mi/joingroup.c 

exccscrvcr/mi/killprogram.c 

ipc/mi/lcavcgroup.c 

graphics/mi/bitreverse.c 

graphics/mi/bitreverse.c 

graphics/mi/bitreverse.c 

graphics/mi/bitreverse.c 

graphics/mi/bitreverse.c 

graphics/mi/bitreverse.c 

graphics/mi/bitrcvcrse.c 

graphics/mi/bitrcvcrse.c 

graphics/mi/loadfile.c 

graphics/rni/loadgfontc 

excc/mi/cxccprogram.c 

cxcc/mi/loadteamfile.c 

drivcrs/vax/deqnax 

exec/m i/Iogoutexecs.c 

graphics/mi/lookupfont.c 

graphics/mi/rastcrclear.c 

exec/m i/maptcarnnamc.c 

auth/mi/mapuid.c 

auth/mi/mapusername.c 

auth/mi/modifyuser.c 

ipc/mi/movcfrom.c 

ipc/mi/movcto.c 

graphics/mi/newraster.c 

drivcrs/m68k/cnct50.c 

io/mi/opcn.c 

io/mi/opcnduplcx.c 

io/mi/opcnfile.c 

io/mi/opcnip.c 

cxcc/mi/lookup.c 

io/mi/opcnstr.c 

io/mi/opcntcp.c 

excc/mi/parsclinc.c 

auth/mi/password.c 

graphics/vax/rasterop.c 

cxccptions/nii/printcrrorx 

io/mi/printfile.c 

cxccptions/m68k/printstack.c 

io/mi/putbigcndian.c 

io/mi/putbigcndian.c 

io/mi/putbigcndian.c 

io/mi/putbigcndian.c 

io/'mi/putbigcndian.c 

io/mi/piitbigcndian.c 

io/mi/putbigcndian.c 
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PutUnsigncd4 

QucryExec 

QueryGroiip 
QueryHosts 
QucryHostsViaCS 
QucryHostsViaMulticast 

QvssDisable 

QvssEnable 
Qvsslnit 
QvssRectangle 
REG 

RasterClcar 

RasterCompileDummyL 
RasterCompileDummyW 
Rasterlnvert 
RasterOp 

RasterOpS 

RasterPrint 

RastcrSet 

Read 

RcadAccess 

RcadDataPackct . . . . 

ReadGenericCharacter 

RcadGencricFont 

Receive 

RcccivcSpcciftc 

ReccivcWithScgment . . 

RelcascFilcRcgion 

Release Instance 

RclcascSpinLock 

RcmoteExccute 

RcmovcFile 

Reply 

RcplyWJthScgmcnt 
RcsctRcccivc 
RcstrictRastcr 

Rcsynch 

RowToColRaster 
Search Bit 
ScarchPathMatch 
Seek 

ScckBlock 

SctBitPtr 

SetBrcak Process 

SctlnstanccOwncr 

SctModc 

SctUpEnvironmcnt . . , 

ShortString 

SimpleText 

SkipToBoc 

SpccLoadProgram 

SpccialClose . . . . , 

StandardKxccptionHandlcr 

TcamOwncr 



io/mi/putbigcndian.c 

exccscrvcr/mi/qucryexcc.c 

ipc/mi/querygroup.c 

cxec/mi/qucryhostsx 

excc/mi/qucryhostscsx 

cxcc/mi/qucryhostsm.c 

graph ics/vax/uscqvss.c 

graphics/vax/uscqvss.c 

graph ics/vax/qvssinitx 

graph ics/vax/q vssrcctanglcc 

graphics/vax/rastcrop.c 

graph ics/mi/rasterclcar.c 

graphics/m68k/rastcrcompile.c 

graphics/m68k/rastcrcompile.c 

graphics/mi/rasterinvcrtc 

graphics/vax/rastcrop.c 

graphics/vax/rastcrop.c 

graphics/mi/rasterprintc 

graphics/mi/rastersetc 

io/mi/readx 

exccptions/m68k/stdexcepLc 

drivers/m68k/cnct3.c 

graphics/mi/readgfontc . 

graphics/mi/readgfontx 

ipc/mi/kcrncllib.c 

ipc/mi/kcmellib.c 

ipc/mi/kcrnellib.c 

graphics/mi/loadfile.c 

io/mi/relcaseinsLc 

locking/mi/spinlock.c 

cxcc/mi/rcmotccxcc.c 

io/mi/rcmovcfilc.c 

ipc/mi/kcrncHib.c 

ipc/mi/kcrncllib.c 

drivcrs/m68k/cnet75.c 

graph ics/m i/rcstrictrastx 

io/mi/rcsynch.c 

graph ics/m68 k/col um norderc 

graph ics/mi/rastcrbbox.c 

excc/mi/lookup.c 

io/mi/scek.c 

io/mi/scckblock.c 

graphics/mi/sctbitptr.c 

io/mi/sctbrcak.c 

io/mi/sctowncr.c 

drivcrs/m68k/cnctxln.c 

cxcc/mi/sctupcnv.c 

exccptions/mi/crror.c 

graphics/vax/drawtcxLc 

graphics/mi/rcadgfont.c 

cxcc/mi/spccloadprog.c 

io/mi/closc.c 

cxccptions/m68k/stdcxccptc 

cxec/mi/tcamowncr.c 
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TcxtBBox 

TryEnetTransmit 

UnaryOp . . . 

UnaryOpS 

UnfreezeHost 

UscQvss 

UscrName 

ValidMagicNum . 

WORDOP 

Wait 

Write 

WriteGfFont 

WriteKernelPacket 

WriteText 

Zero 

_Open 

abort 

acos . . . . . . 

align 
allock . 
artoa 
asin 

asympt 

atari 
atan2 
atoar 
bcopy 

botch 

cabs 

calloc 

ceil 

cfree 

chdir . . . . . 

clear 

clcarcrr 

coffee J>rcak 

compilcW 

cos ..... . 

cosh 
debug 
enctaddress 
enopen 

cxp 

fabs 

floor 

free 

gct_Ap_Fp 

gfjiewjw . . . 

gf_paint 

hvTcst 

hypot 

if 

JO ..... . 

jl 



graphics/mi/tcxtbbox.c 

drivcrs/m68k/enct3com.c 

graphics/vax/rasterop.c 

graphics/vax/rastcrop.c 

cxccptions/mi/freczchostc 

graph ics/vax/uscqvss.c 

auth/mi/uscrnamc.c 

excc/mi/validmagicnuni.c 

graphics/mi/rastcrclear.c 

exec/mi/ waitc 

io/mi/writc.c . 

graphics/mi/writegfonte 

drivers/m68k/enet3.c 

graphics/vax/gentextc 

mem/mi/zero.c 

io/mi/_open.c 

exceptions/m68k/aborLc 

math/mi/asin.c 

exec/mi/loadteamfilc.c 

me m /mi/m alloc .c 

auth/mi/artoa.c i 

math/mi/asin.c 

math/mi/j0.c 

math/mi/atan.c 

math/mi/atan.c 

auth/mi/atoar.c 

mcm/mi/bcopy.c 

mem/mi/malloc.c 

math/mi/hypotc 

mem/mi/calloc.c 

math/mi/ floonc 

mem/mi/calloc.c 

io/mi/chdir.c 

drivci"s/m68k/enctxln.c 

io/mi/clrcrr.c 

drivcrs/vax/dcqna.c 

graph ics/m68k/rastcrcompile.c 

math/mi/sin.c 

math/mi/sinh.c 

drivcrs/m68k/enet3.c 

drivcrs/m68k/cnetxln.c 

drivcrs/m68k/cnctxln.c 

math/mi/cxp.c 

math/mi/ fabs.c 

matli/mi/tloonc 

mcm/mi/malloc.c 

cxccptions/vax/printstack.c 

graph ics/mi/writegfonte 

graphics/mi/writegfonte 

graphics/mi/tcxtbbox.c 

matli/mi/hypotc 

graphics/vax/gentextc 

math/mi/j0.c 

math/mi/jl.c • 
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log 

loglO 

malloc . . 

mc68kenread 

mc68kenwrite 

mktemp 

one_sip 

pack2 . . . 

pack4 

packpair 

packstr 

pow 

print_pc . . 

rcalloc . 

returns :. 

s_gete 

satan 



sm 

sinh 

sinus 

sizeof 

sqrt 

swab ...... 

swap! 
switch 
system 
tan 

tanh 

u_getc 

ungetc 

unlink 

unlockAndGctSpace 

unlockcdFrcc . . . 

unlockcdGivcToMalloc 

unlockcdMalloc 

unlockcdllcalloc 

xatan 

yo • 

yi 

yn 

AddCList 

AddDList 

AddQucuc .... 

AddSList 

Any 

AwaitScndRcply 

Backspace 

BuffcrValid .... 

CrRL 

ClcarLocalNamcs 

ClcarModificdPagcs 

Concat 

Convcrt_num . . . 



math/mi/jn.c 

math/mi/log.c 

math/mi/log.c 

mcm/mi/malloc.c 

drivcrs/m68k/enetxln.c 

drivcrs/m68k/enctxln.c 

io/mi/mktemp.c i 

drivers/vax/deqnax 

excc/mi/setupenv.c 

excc/mi/setupenv.c 

exec/mi/setupenv.c 

cxec/mi/setupcnv.c 

jtnath/mi/pow.c 

\ixceptions/vax/printstack.c 

mcm/mi/malloc.c 

gtaphics/vax/gcntextc : 

io/mi/getbigendian,c 

math/mi/atatLc 

math/mi/sinx 

math/mi/sinh.c 

math/mi/sin.c 

drivcrs/m68k/cnct3x . 

math/mi/sqrtc 

mem/mi/swabshorte 

drivcrs/m68k/cnet50.c 

graphics/vax/gcntexLc 

cxcc/mi/systcm.c 

math/mi/tan.c 

math/mi/tanh.c 

io/mi/getbigcndian.c 

io/mi/ungctcc 

io/mi/unlink.c 

mcm/mi/ma11oc.c 
, mcm/mi/malloc.c 

mcm/mi/mal1oc.c 

mcm/mi/malloc.c 

mcm/mi/malloc.c 

math/mi/atan.c 
. math/mi/j0.c 

math/mi/jl.c 

math/mi/jn.c 

packagcs/mi/clistc 

packagcs/mi/dlistx 
. packagcs/mi/qucuac 

packagcs/mi/slistc 

strings/mi/any.c 

sa/mi/ikee 

sa/mi/flushfillc 
. sa/mi/flushfill.c 

tcrnilib/mi/tgoto.c 

naming/mi/cIcarlocal.c 

proccss/mi/clcarpagcsx 

strings/mi/concatc 
. strings/mi/cbnvcrtnum.c 
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Cooked sa/mi/flushfill.c 

CopyMsg sa/mi/ikcc . 

Copy_str . . strings/mi/copystr.c 

Create process/mi/create.c 

CreateHost proccss/mi/crcatchosLc 

CrcatcProccss proccss/mi/creatcproc.c 

CrcatcSclcctionlnstance servicc/mi/selectc 

CreateTearn . proccss/mi/createteam.c 

Creator proccss/mi/creator.c 

DefineLocalName naming/mi/dcflocal.c 

DefineTempArea naming/mi/dcftcmparea.c 

Delay time/mi/delay.c 

Destroy proccss/mi/destroy.c 

DestroyHost process/mi/destroyhostc 

DestroyProcess proccss/mi/destroyproc.c 

DisplayFields vgts/mi/fields.c . 

Echo sa/mi/flushfill.c 

EditField vgts/mi/fields.c 

EditLine vgts/mi/cditline.c 

EditStdFld vgts/mi/fields.c 

EmptyCList packagcs/mi/clistc •: 

EmptyDList packagcs/mi/dlistc 

EmptyQueue . packagcs/mi/queuex 

EmptySList packagcs/mi/slistc 

EmptyStack packages/mi/stack.c 

Equal strings/mi/cqual.c 

ExtractHost proccss/m i/extracthostx 

FillBuffer . . sa/mi/flushfill.c 

FirstCList packagcs/mi/clistc 

FirstDList packagcs/mi/dlistc 

FirstSList packagcs/mi/slistc 

FlushBuffer sa/mi/flushfill.c 

FormatFoniiat vgts/mi/ficlds.c 

Forward saconsolc/mi/dummyikcc 

FreczcHost proccss/mi/frcczchostc 

GctAbsolutcName naming/mi/gctabsnamc.c 

GctBuffcrcdLine sa/mi/flushfill.c 

GetContcxtld . naming/mi/namcscnd.c 

GctContcxtName naming/mi/gctctxnamc.c 

GctEvent vgLs/mi/uscmouscc 

GctField • vgts/mi/ficlds.c 

GctFilcName naming/mi/gctfi1cnamc.c 

GctGraphicsEvcnt vgLs/mi/uscinousc.c 

GctGraphiesStatus vgts/mi/uscmousc.c 

GclllostPid naming/mi/gcthostpid.c 

GctMorcMullocSpace sa/m68k/gctmorcmaUoc.c 

GctMouscEvent vgts/mi/uscmouse.c 

GctMouscStatus vgts/mi/uscmousc.c 

GctObjcctOwncr proccss/mi/objcctowncr.c 

GctPid naming/mi/gctpid.c 

GctRcmotcTime timc/mi/remotctiincc 

GctRcply saconsolc/mi/dummyikcc 

GctTPY vgts/mi/vtty.c 

GctTcamRoot proccss/mi/gcttcam rootc 
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GctTcamSize proccss/mi/gcttcamsizcc 

GctTimc timc/mi/gcttime.c 

GotAnlnt . sa/vax/initmts.c 

Hex value smngs/mi/hexvalue.c 

IgnoreRetry ' narning/mi/ignoreretry.c 

IiiitCList . . • : packages/mi/clistc 

InitDList packagcs/mi/dlistc 

InitQueue packages/mi/queue.c 

InitSList ■■■. .... packages/mi/shstc- ,, 

ImtStack- pa ? ka ?? /, !; , /i? taC , - 

IsCookcd ,. Sa/ / m ^ US K« . 

IsEcho sa/mi/flushfm.c ^ 

IterCList , packages/mi/clistc -, 

IterDList packages/mi/dlisLc 

I^rSList ." packa ?^ Q m w^Lin, ' 

v r^ rawio/m68k/sunlrawio.c -■•-. 

KKetchar rawio/m68k/sunlrawio.c ". 

Keetconfig ■-; rawio/rn68k/sunlrawio.c -».c 

Kjsetcontcxt .... rawio/m68k/sunlrawio.c >.■-. 

K^ctmcmsize ™ [ ?' m *iy™ n \™ti 

K eetseemaD rawio/m68k/sunlrawio.c • ... 

K mayget ;c,l rawio/m68k/sunlrawio.c 

K'oroctvDe rawio/m68k/sunlrawio.c 

K Dutchar rawio/m68k/sunlrawio.c • -c 

v% uts . . M rawio/m68k/sunlrawio.c =. 

Ksetcdntext >*'' rawio/m68k/sunlrawio.c 

K~setsegmap V -m rawio/ni68k/sunlrawio.c 

K ticks rawio/m68k/sunlrawio.c 

Aversion '-' • rawio/m68k/ r sunlrawio.c 

LitCList ■■* packages/mi/cHsLc 

LastDList .......... packagcs/mi/dlisu 

LastSUst -.■:•■•■■ packagcs/mi/shstc 

lx)wer i strings/mi/lowcr.c 

MakcHcxDigit . sa/mi/makchcxdigit.c ■■.;■■ 

Meditate unix-compat/mi/signal.c 

ModifyPad vgis/mt/opcnpacU 

NRcadDcscriptor naming/mi/nrcaddesc.c 

NWritcl)cscriptor naming/mi/nwntcdesc.c 

NamcCachcAdd . naming/mi/namecache.c 

NamcCachcDclcte naming/mi/namccache.c 
NamcCachcLookup ....... namtng/mi/namccachex 

NamcSend . namin&/m./namcscnd.c 

NoEcho sa/mi/flushfill.c 

Null str strings/mi/nuHsirx •■• 

OpcnAndPositionPad vgts/mi/opcnpadx 

OpcnConfigFile V qucry/mi/qwconfig.c 

OpcnPad< ! vgts/mi/opcnpad.c !.-• 

ParscFomiat vgts/mi/ficldsx: . ; 

PopStack packagcs/mi/stack.c 

PrimeCache naming/mi/primccachc.c 

PushStack * packagcs/mi/stack.c ■ 

PutField ^ vgts/mi/ficlds.c 

PutUntilConvcrsion vgts/mi/fic!ds.c 

QucryKcmct proccss/mi/qucrykcrn.c 
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QueryPad 

QueryPadSize . . . . 

QueryProccssPriority 

QueryProcessState 

QueryProccssorUsage 

QueryWorkstationConfig 

Raw 

RawGetchar 
ReadDescriptor 
ReadProcessState 
ReadStdFld 

Ready 

RealFiUBufter 

RealFlushBufFer 

RedrawPad 

RcgisterObject 

RcgistcrServer . . . . 

RemoveCList 

RemoveDList 

RcmoveQueue . 

RcmoveSList 

Rename 

ReplyWithSeg 

ReportNamingStats 

ResetTTY 

ResolveLocalName 

ReturnHostStatus . . . 

Return Modified Pages 

SameTeam 

SelcctPad 

Send 

SctObjcctOwncr . . . 

SctPid 

SctProccssPriority 

SctTcamPriority 

SctTcamSizc 

SctTime 

SctUscrNumber 

SctVgtBanncr 

Shiftjeft 

Size 

SpccialSprintf . . . . 

StrToFormat 

Suicide 

TcamRoot 

TransfcrHost 

UndcfincLocalName 

Unfreeze Host 

UnrcgistciObject 

UnrcgistcrScrvcr 

UpdatcHostStatus 

Upper 

User 
ValidPid 



vgts/mi/openpa&c 

vgts/mi/openpad.c 

process/mi/priority.c 

process/mi/queryprocessx 

proccss/mi/queryusage.c 

query/mi/qwconfig.c 

sa/mi/flushfill.c 

sa/mi/flushfill.c 

naming/mi/readdesc.c . 

process/mi/readprocess.c . 

vgts/mi/fields.c 

process/m68k/ready.c 

sa/mi/flushfill.c . 

sa/mi/flushfilLc .- 

vgts/mi/usemouse.c .. 

service/mi/register.c 

service/mi/register.c 

packagcs/mi/clistc 

packages/mi/dlistc 

packagcs/mi/qucuc.c 

packages/mi/slistc 

naming/ mi/rcname.c 

saconsole/mi/dummyikc.c 

process/mi/exitx 

vgts/mi/vtty.c c 

naming/mi/rcsolvelocal.c 

service/mi/hoststatus.c 

proccss/mi/rcturnpagcs.c 

process/mi/samctcam.c 

vgts/mi/openpad.c 

sa/mi/ikc.c 

proccss/mi/objectowncr.c 

naming/mi/sctpid.c 

proccss/mi/priority.c 

proccss/mi/scttcamprio.c 

proccss/mi/scttcamsizc.c 

timc/mi/scttime.c 

uscr/m i/sctuscrnumber.c 

vgts/mi/sctbanner.c 

strings/mi/shiftlcftx 

strings/mi/sizc.c 

vgts/mi/ficlds.c 

vgts/mi/ficlds.c 

proccss/ini/dcstroy.c 

proccss/mi/teamroot.c 

proccss/mi/transfcrhostc 

naming/mi/undcflocal.c 

proccss/mi/unfrcczchostc 

scrvicc/mi/rcgister.c 

scrvicc/mi/registcr.c 

scrv icc/m i/hoststatus.c 

strings/mi/upper.c 

uscr/mi/user.c 

proccss/mi/validpid.c 
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Vsasu 

Wakcup 

WatchForBreak 

WriteDcscriptor 

WritcProcessState 

.Receive 

_doprnt 

_doscan . . . 

_getccl 

_innum 

_instr 

.start 

_strout . . . 

abort 

abs 

align 

asctime 

atof .... 

atoi 

atol 

chmod 

clearenv 

close .... 

closedir 

control 

copyenv 

crcat 

crypt .... 

ct_numb 

ctime 

cvt 

debug 

decprint . . . 

dysize 

cevt 

encrypt 

exit 

fbmode . . . 

fclose 

fcvt 

feof 

ferror 

fflush .... 

fgetc 

fgcts 

fopen 

fprintf 

f^utc . . . . 

fyuts 

frcad 

frcopen 

frcxp 

fscanf . . . . 

fscek 



sa/vax/Vsasu.c 

time/mi/wakeup.c 

unix-compat/mi/signal.c 

naming/mi/writedesc.c 

process/mi/writeprocess.c 

saconsole/mi/dummyikcc 

stdio/mi/doprntc 

stdio/mi/doscan.c 

stdio/mi/doscanx 

stdio/mi/doscan.c 

stdio/mi/doscan.c 

sa/rn68k/_startc 

stdio/mi/stroutc 

sa/mi/abortc 

numeric/mi/abs.c 

proccss/mi/teamrootc 

time/mi/ctime.c 

strings/rni/atof.c 

strings/mi/atoi.c 

strings/mi/atol.c 

unix-compat/mi/unix-io.c 

naming/mi/clcarenv.c 

unix-compat/mi/unix-io.c 

naming/mi/closedirx 

sa/mi/flushfill.c 

naming/mt/copycnv.c 

unix-compat/mi/unix-io.c 

strings/mi/crypLc 

timc/mi/ctime.c 

timc/mi/ctime.e 

strings/mi/eevtc 

sa/mi/ikee 

saconsolc/mi/printf.c 

timc/mi/ctimc.c 

strings/mi/cevtc 

strings/mi/crypLc 

proccss/mi/exitc 

rawio/m68k/sun lrawio.c 

stdio/mi/fclosc.c 

strings/mi/ccvLc 

stdio/mi/fcrror.c 

stdio/mi/fcrror.c 

stdio/mi/fflush.c 

stdio/mi/fgetec 

stdio/mi/fgcts.c 

stdio/mi/fopcn.c 

stdio/mi/fprintf.c 

stdio/mi/fputc.c 

stdio/mi/ffrutsx 

stdio/mi/rdwr.c 

stdio/mi/frcopenx 

numcric/vax/frcxp.c 

stdio/mi/scanf.c 

stdio/mi/fscck.c 
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fctat 

ftell 

ftime 

fwrite . . 

gcvt 

getenv 

gets 

getw 

getwd . . 

gmtime 

hexprint 

index 

initints 

Initstate . 

linecontrol 

linedata 

lineget 

linereadyrx 

link . . 

localtime 

Iseek 

nevercalled 

octprint 



open 

opendir 

pBreathOfLife 

pRcmotcForward 

pRcmotcFoward 

pRemotcMovcFromRcq 

pRemotcMovcToReq 

pRcmotcRcccivcSpecific 

pRemotcRcply 

pRemotcScnd 

printf 

puts 
putw 
qsl 
qsexc 

qsort 

qstcxc 

rand 

random 

read 

rcaddir 



rename 

rcturn_K_ticks 

rewind 

rindcx 

sbrk . . . 

scanf 

scckdir 

sctbuf 

sctccho 

setenv . . . 



unix-compat/mi/unix-io.c 

stdio/mi/ftell.c 

time/mi/ctime.c 

stdio/mi/rdwr.c 

strings/mi/gevtc 

naming/mi/gctenv.c 

saconsole/mi/gets.c 

stdio/mi/gctw.c 

naming/mi/getwd.c 

time/mi/ctime.c 

saconsole/mi/printf.c 

strings/mi/indcx.c 

sa/vax/initints.c 

numeric/mi/random.c 

rawio/m68k/sunlrawio.c 

rawio/m68k/sun Lrawio.c 

rawio/m68k/sun lrawiox 

rawio/m68k/sun lrawio.c 

unix-compat/mi/unix-io.c 

time/mi/ctime.c 

unix-compat/mi/unix-io.c 

sa/m68k/_start.c 

saconsolc/mi/printf.c 

unix-compat/mi/unix-io.c 

naming/mi/opcndir.c 

sa/mi/ikc.c 

sa/mi/ikee 

sa/mi/ikcx 

sa/mi/ikee 

sa/mi/ikc.c 

sa/mi/ikc.c 

sa/mi/ikc.c 

sa/mi/ikee 

saconsolc/mi/printf.c 

saconsolc/mi/putsx 

stdio/mi/putw.c 

numcric/mt/qsortc 

numcric/mi/qsortc 

numcric/mi/qsortc 

numcric/mi/qsort.c 

numcric/mi/rand.c 

numcric/mi/random.c 

unix-compat/mi/unix-io.c 

naming/mi/rcaddir.c 

naming/mi/rcnamc.c 

sa/vax/initints.c 

stdio/mi/rcwind.c 

strings/mi/rindex.c 

unix-compat/mi/sbrk.c 

stdio/mi/scanf.c 

naming/mi/scckdir.c 

stdio/mi/sctbuf.c 

rawio/m68k/sun lrawio.c 

naming/mi/sctcnv.c 
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setkey strings/mi/crypLc 

sctstatc numcric/mi/random.c 

signal unix-compat/mi/signal.c 

sleep timc/mi/slcep.c 

sprintf stdio/mi/sprintf.c 

srand numcric/mi/rand.c 

srandom numeric/mi/random.c 

sscanf stdio/mi/scanf.c 

stat unix-compat/mi/unix-io.c 

stdinit unix-compat/rm7unix-io.c 

stime ' timc/mi/ctime.c 

strcat strings/mi/strcatc 

strcatn strings/mi/strcatn.c 

stremp strings/mi/strcmp.c 

strempn strings/mi/strcmpn.c 

strcpy strings/mi/strcpy.c 

strcpyn strings/mi/strcpyn.c 

strlen strings/mi/strlcn.c 

strncat strings/mi/strncatc 

strnemp strings/mi/strncmp.c 

strncpy strings/mi/strncpy.c 

strsave strings/mi/strsave.c 

Sunday time/mi/ctime.c 

tdecode . tcrmlib/mi/tcrmcap.c 

tclldir naming/mi/tclldir.c 

tgetent tcrmlib/mi/tcrmcap.c 

tgctflag tcrmlib/mi/termcap.c 

tgctnum tcrmlib/mi/tcrmcap.c 

tgctstr tcrmlib/mi/tcrrncap.c 

tgoto tcrmlib/mi/tgoto.c 

time timc/mi/ctimc.c 

timczonc timc/mi/timczone.c 

tnamatch tcrmlib/mi/tcrmcap.c 

tnchktc tcrmlib/mi/tcrnicap.c 

tputs tcrmlib/mi/tputs.c 

tskip tcrmlib/mi/tcrmcap.c 

umask unix-compat/mi/unix-io.c 

unix_crrno unix-compat/mi/unix-io.c 

vdir_to_stat unix-compat/mi/unix-io.c 

wordchar sa/mi/flushfill.c 

write unix-compat/mi/unix-io.c 
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CTRL-a 

CTRL-b 

CTRL-d 

CTRL-e 

CTRL-f 

CTRL-g 

CTRL-h 

CTRL-i 

CTRL-k 

CTRL-t 

CTRL-U 

CTRL-W 

CTRL-Z 

ESC-b 

ESC-d 



2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-10 
2-11 
2-11 
2-11 



ESC-f 2-11 
Esc-h 2-11 
.Open 22-3 

[bin] 3-1 

Abort 2-6,27-8 

Abort Command 2-10 

Aborted 32-2 

Abs 26-1 

Acquire A rgumcntSpinLock 23-2 

Acquired lobalSpinl^ock 23-2 

AcquircSpinlxxk 23-1 

AddCall 29-9 

Addcorr 43-2 

Addltcm 29-9 

AddUser 35-2 

All 29-14 

Alto 10-1 

Amaze 4-1 

ANSI 46-2 

ANSI terminal 2-3 

ANSI virtual terminal 2-3, 2-6 

Any 30-2 

Append Only 22-2,33-1 

Ar 4-1 

Arrowheads 10-1 

Asctimc 30-1 

Atof 30-2 

Atoi 30-2 

Atol 30-2 

Attributes 10-2 

Authenticate 35-2 

Authentication 35-1, C-4 

Authentication server 31-5, 35-1 



Authservcr 35-1 

Autobooting 16-2 

AVT 2-3,2-6 

AVT Escape Sequences 46-1 

Awaiting reply 31-5* 

AwaitingReply 27-9 

Awoken 32-2 

Background 42-1 

Background Processes 31-7 

Backspace 46-1 

Bad Address 32-2 

BadArgs 32-2 

Bad Block No 32-2 

Bad Buffer 32-2 

Bad Byte Count 32-2 

Bad Forward 32-2 

Bad Process Priority 32-2 

Bad State 32-2 

Bare kernel mode 27-8 

Beginning of Buffer 45-1 

Beginning of Line 2-10 

Bell 46-1 

Big-endian 32-1 

Biopsy 4-1 

Bitcompile 4-1 

Bits 7-1 

Blank tines B-l 

BlkslnRlc 22-6 

BlockPosition 22-6 

Blocks 33-1 

BlockSi/e 22-6 

Bit 24-2 

Boise 4-2 

Booting 2-4 

Break-Process 2-10 

BuffcrlEmpty 22-5 

Build 8-1 

Busy 32-2 

Byte order 32-1 

Byte-swapping 32-1 

C 4-2 

Cadlinc 2-5 

Cailoc 24-1 

Cat 4-2 

Cc68 4-2 

Cd 3-2.4-2 

Center Window 2-7 

Cfrcc 24-1 

Change Context 3-2 

Change Current Context 25-1 
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Change Directory 3-2,4-2 
QiangcDircctory 25-1 
Changeltcm 29-10 
Character Set 46-3 
Character strings 30-2 
Chdir 25-1 
Checkers 4-2 
Checkexecs 4-2 • 
Q 4-3 
Circles 10-1 
Gear 4-3.24-2,46-2 
Clear AVT 46-1 
Clear To EOL 46-2 
Dear To EOS 46-2 
Clcarcnv 25-6 
ClcarEof 22-5 
aearLocalNames 25-3 
ClearModificdPagcs 27-1 
Gick 2-6 
Clock 4-3 
Close 22-4 
Co 4-3 

Command Arguments 3-6 
Command processing 31-7 
Commands 10-2,10-7 
Compile command 18-1 
Compiling 18-1 
Concat 30-2 
Config Files 19-1 
Configuration 19-1 
Console 36-3 
Context 4-3,34-2 
Context Directories 34-9 
Context Request 34-6 
Contexts 3-1 
Control 2-10 
Convcrt_num 30-2 
Cooking 29-2,46-3 
Copy 24-1 
Copy files 4-3 
Copy_str 30-3 
Copycnv 25-6 
Cp 4-3 
Cpdir 4-3 
CR Input 29-2 
Create 27-7 

Create Duplex Instance 33-4 
Create Executive 2-7 
Create lustjiiicc 33-3. 46-3 
Create Instance Retry 34-11 
Create View 2-7 
CrcatcIXiplcx Instance 22-3 
CrcatcExcc 46-5 
CrcatcGroup 27-8 
CrcatcMost 27-6 
Crcatclnstancc 22*3 
CrcaicPipclnslancc 22-7 
CrcatcProccss 27-1 
CrcatcSDF 29-8 
CrcatcTcam 27-2 



CreatcVGT 29-11 
CreateView 29-2 
Creator 27-2 
Crypt 30-2 
CSname 34-2 
CSNH server 34-2 
Ctime 30-1 
CTRL-\ 45-1 
CTRL-I 45-1 
CTRL-n 45-1 
CTRL-p 45-1 
CTRL-q 45-1 
CTRL-y 45-1 
Current object 10-3 
Cursor Backward 2-10,46-2 
Cursor Down 45-1 
Cursor Forward 2-10,46-2 
Cursor Position 46-2 
Cursor Up 45-1,46-2 
Cursor Word Backward 2-11 
Cursor Word Forward 2-11 
Cx 4-3 

Dale 4-3,4-9,29-6 
Date 4-3 
Debug 4-3 
Debugger 9-1,37-1 
Dcbugvgts 4-3,46-4,46-5 
Default Context 34-4 
DcfaultRoolMcssagc 28-2 
DcfaullSclcctionRcc 28-3 
DcfaultView 29-1 
Define 4-3 
Define Font 29-11 
DcfinelxwalNamc 25-2 
DcfincSymbol 29-8 
DcfincTcmpArca 25-3 
DEL 46-2 
Delay 30-1 
Dclcorr 43-2 
Delete Char 46-2 
Delete Character 2-10 
Delete Character Backward 2-10 
Delete Character Forward 2-10 
Delete Executive 2-7 
Delete Last Character 2-10 
Delete Line 2-10.46-2 
Delete to Beginning of line 2-10 
Delete to End of Line 2-10 
Delete to Start of Line 2-10 
Delete View 2-7 
Delete Word Backward 2-10 
Delete Word Forward 2-11 
Dclctcltem 29-9 
DclctcSDF 29-8 
DclctcSymbol 29-9 
DclctcUscr 35-2 
DclctcVGT 29-1 
Dclcxcc 4-3 
Destroy 4-3.27-7 
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DcstroyAuthRcc 35-2 
Destroy Host 27-6 
DestroyProccss 27-2 
Device Error 32-2 
Device server 31-3, 36-1 
Device type 36-1 
Diff 4-3 

DiffercntBytcOrdcr 32-1 
DiffcrcntlKCByteOrder 32-1 
Discard Reply 32-2 
DiscardOutput 29-2 
Disk 36-2 
Displayltcm 29-11 
Do 4-4 
Domake 4-4 
Dopar 4-4 
Doseq 4-4 
Draw 4-4,4-9 
Duplicate Name 32-2 

Echo 4-4.29-3 
Ecvt 30-2 
EditLine 29-5 
Editor 4-9.14-1 
EditSymbol 29-8 
Emacs 4-9 
End of Buffer 45-1 
End of File 2-10,32-3 
End of Line 2-10 
EndSymbol 29-8 
Environment Variables 3-6 
Eof 22-5 
Equal 30-3 
ErrorString 27-8,30-4 
ESC-. 45-1 
ESC-. 45-1 

ESC-HACKSPACB 45-1 

ESC-del 45-1 
ESC-d 45-1 
ESC-t 45-1 
Escape 2-10 
Escape Sequences 46--1 
Ethernet 36-1 
Event Request 46-4 
Example 29-15 
Exception handler 31-7 
Exception handling 31-7 
Exception Request 37-1 
lotccplion server 31-3 
Exec 3-1,46-5 
Exec Control 2-8,3-1 
Exec server 31-4 
Excel 28-4 

ExccProgram 28-2,42-1 
Exccservcr 3-1 
Execution 18-2 
Executive 3-1,27-8 
ExccuUvcs 31-4 
Exit 27-8,31-6 
Expansion Depth 2-8 



ExtractHost 27-6 

FAppend 22-1,33-2 
FCreate 22-1. 33-2 
FDirectory 33-3 
Fexecute 4-4,33-3 
Fields 21-1 
File Modes 22-1,33-2 
File Types 22-2.33-1 
FileExccption 22-6 
Fileld 22-8 
FileServer 22-8 
FilcType 22-8 
Filled Rectangle 29-6 
FmdSelectcdObject 29-13 
First Team 31-5 
Fixed Length 22-2,33-2 
Rush 22-5 
FModify 22-1.33-3 
Followup message 34-11 
Font 29-11 
Fonts 10-1.10-2.12-3 
ForceScnd 27-9 
Foreground 42-1 
Forward 27-9 
Forwarder 27-10 
Framcbuffcr 36-3 
FRead 22-1.33-2 
Free 24-1 . 
Freemem 4-4 
FreezeHost 27-7 
Ftime 30-1 
FullUserName 35-2 

Gcvt 30-2 
General Line 29-6 
General Text 29-7 
Get Absolute Name 34-7 
Get Context Id 34-7 
Get Context Name 34-8 
Get File Name 34-8 
GctAbsolutcNamc 25-3 
GctContextld 25-3 
GctContcxtNamc 25-4 
Gctenv 25-5 
GctEvent 29-12 
GctFtlcName 25-3 
GctGraphicsEvcnt 29-12 
GctGraphicsSlalus 29-12 
GelMorcMallocSpacc 24-2 
GctMouscClick 29-13 
GctMouscOrKcyboard 29-13 
GctObjcctOwncr 27-2 
GctPid 27-3 
GctRcmotcTimc 30-2 
GclRcply 27- 10 
GctSigncd 22-9 
GclTcamRoot 27-3 
GctTcamSize 27-3 
GclTimc 30-1 



V-Syslem 6.0 Reference Manual 



17 June 1986 



Index-4 



GctTTY 29-14 
GclUnsigned 22-9 
Getwd 25-1 
Gftodvi 4-4 
Gftype 4-4 
GivcToMalloc 24-2 
Global servers 31-4 
Gmtimc 30-1 
Graphics Commands 2-8 
Grep 4-4 

Groups 10-1.10-3.10-5.10-9 
Guest 42-1 

Has Substructure 32-3 
Helper process 31-1 
Helper Processes 31-3 
Heterogeneity 3-7 
Hcx.value 30-3 
History 3-5 
Hit Detection 29-13 
Home directory 4-6 
Horizontal line 29-6 
Host selection 28-3.42-1 
Host status 42-1 

I/O 22-1 

I/O Protocol 33-1 

Ident 4-4 

Ignored 46-2 

lKC_UTrLE_ENDIAN 32-1 

Illegal Name 32-3 

Illegal Request 32-3 

Index 30-2.46-2 

Initial process 18-1 

Initial slack 18-1 

Initialization 18-3.31-5 

Inqucry program 39-11 

InquircCall 29-9 

Inquircltcm 29-9 

Insert Char 46-2 

Insert Line 46-2 

Insert Wilh l-ighth Bit Set 45-1 

Installation C-l 

Instances 4-4 

Interactive 22-2,22-8,33-2 

Internal Error 32-3 

Internet Server 4-4,39-1 

Interprocess Communication 13-1, 27-1, 27-9 

Interrupt Program 2-8 

Invalid Context 32-3 

Invalid File Id 32-3 

Invalid Mode 32-3 

Inverse Video 46-2 

IO Break 32-3 

IO Protocol 17-2 

IP/TCP 4-8.39-1 

Iphost 4-4 

Iptclnct 4-8 

Item 29-5.29-6 

Item Type 29-6 



JoinGroup 27-9 

Kernel mode 18-2 
Kernel server 31-3 
Kernel Timeout 32-3 
Kill Break 2-10 
Kill Program 2-8,46-3 
Kill Word Forward 45-1 
Killprog 4-4 

LeaveGroup 27-9 

Left Button 2-12,29-4 

Left Mouse Button 14-7 * 

Left + Middle Buttons 2-12,29-4 

Left+ Right Buttons 2-12,29-4 

LF Output 29-3 

UbV.a 18-1 

Line 29-6,29-8 

Line Editing 2-10. 29-3, 29-5. 45-1, 4fr4 

LincBufler 29-3 

Linking 18-1 

Listdesc 4-4 

Listdir 4-4 

Little-endian 32-1 

UTTLE.ENDfAN 32-1 

UTTLEJiNDIAN.HOST 32-1 

Loader 18-2 

Loading 31-5 

LoadProgram 28-1.42-1 

Locaitime 30-1 

Locking 23-1 

Login 3-2,4-4 

Logout 3-3 

Longjmp 30-4 

Lower 30-3 

MacDraw 10-1 

Machine-relative servers 31-3 

Mail 4-5 

Make 8-1 

Make Bottom 2-8 

Make Top 2-8' 

Malloc 18-1.24-1 

MapUID 35-2 

MapUscrNamc 35-3 

Math 26-1 

Mem server 4-5,40-1 

Memory server 31-5 

Menu 21-1.29-14 

Menu. View Manager 2-7 

Message Format Conventions 32-1 

Mctafont 4-5 

Mf 4-5 

Middle Mouse Button 14-7 

Middle + Right Buttons 2-12,29-4 

Migratcprog 4-5 

Migration 3-2,3-3,4-5 

Mode 33-3 

Mode Not Supported 32-3 

Modes 22-1.33-2 



V-Syslcm 6.11 Reference Manual 



17 June 1986 



Indcx-5 



Modify File 33-8 

ModifyPad 29-4 

ModifyUscr 35-3 

Mon 4-5 

Monasteries 18-1 

More Replies 32-3 

Mouse 2-6, 14-7, 36-2 . 

Mouse emulation 2-12 

Move Edges 2-8 

Move Edges 4- Object 2-8 

Move Viewport 2-8 

MoveFrom 27-10 

MoveTo 27-10 

MulU Block 22-2,33-2 

Multi-manager 32-3 

Multi-manager context directory 34-11 

Name 4-5 

Name Request 34-5 

NameCachcAdd 25-4 

NamcCachcDclctc 25-5 

NamcCachcLookup 25*5 

Names B-l 

NameSend 25-3 

Naming Protocol 34-1 

Netwatch 16-4 

New Line 46-1,46-2 

Newterm 4-5,46-1,46-4 

Next Line 46-2 

Nibs 10-L10-2 

NModiryRlc 33-8 

No Group Desc 32-3 

No Memory 32-3 

NoPDs 32-3 

No Permission 32-3 

No Process Descriptors 32-3 

No Server Resources 32-3 

No IDs 32-3 

No Team DcscrijHors 32-3 

NoCursor 29-3 

Nonexistent Process 32-4 

Nonexistent Session 32-4 

Not a Context 32-4 

Not Awaiting Reply 32-4 

Not Found 32-4 

Not Here 32-4 

Not Readable 32-4 

Not Writcable 32-4 

Nouns 10-2 

NQucryFilc 33-8 

NRcad l)cscriptor 34-10 

NRcadDcscriptor 25-2 

NUL 46-1 

Null devices 36-4 

Null.str 30-3 

Numeric 26-1 

NWritc Descriptor 34-10 

NWritcDcscriptor 25-2 

Object Descriptors 34-9 



OK 32-2 
Open 22-2 

OpcnAndPositionPad 29-4 
OpenDuplex 22-3 
OpcnFile 22-3 
Opcnlp 22-7 
OpenPad 29-4,46-3 
OpcnStr 22-8 
OpcnTcp 22-7 
Outline 29-6 
Ovals 10-1 

Pad 2-3 

PadFindPoint 29-5 

Paged output mode 2-11 

Pagemode 4-6 

PagcOutput 29-3 

PagcOutputEnable 29-3 

Pascal 4-6 

Password 4-6,35-3 

Patterns 104,10-2 

Pc68 4-6 

Per-process area 18-5 

Performance Measurement 13-1 

Personal name 4-6 

Photo 4-9 

Point 29-7 

Polyline 29-7 

Popup 29-14 

Postscript 10-8 

Power Failure 32-4 

Press 10-8,10-9 

PrcssEdit symbol 10-6,10-9 

Previous Word 2-11 

PrimcCachc 25-5 

Print 10-8,10-10 

PrintError 30-4 

Prinlf 22-1 

PrintFilc 22-9 

Process 27-1 

Process Group Operations 27-8 

PROM monitor 27-8 

Protocol 31-1 

Protocol conversion 39-1 

Pseudo-processes 31-1 

Public 43-1 

Public Context 34-4 

PutSigncd 22-9 

IHilUnsigncd 22-9 

Pwd 3-2.4-6 

Pwx 4-6 

Q 4-6 
Qsort 30-4 
Query 4-6 
Query File 33-8 
Query Instance 33-4, 46-3 
Query Name 34-6 
Qucrycxcc 4-6 
QucryGroup 27-9 
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Qucryllosts 28-3 
QucryKcrnel 27-3 
QucryPad 29-4 
QucryPadSize 29-4 
QucryProccssorUsage 27-3 
QucryProccssPriority 27-4 
QucryProccssState 27-4 
QucryWorkstationConfig 19-1 
Quote Character 45-1 
Quoting Arguments 3-6 
QVSS 36-4 

RAM disk 31-5 

Rand 26-1 

Ranlib 4-6 

Ranlib68 4-6 

Raster 29-7 

Raw 29-2 

Res 4-6 

Rcsdiff 4-6 

Rcsmcrgc 4-6 

Re-Display Input 45-1 

Read 22-5 

Read Descriptor 34-10 

Read Instance 33-6,46-3 

Readable 22-2,33-1 

RcadDcscriptor 25-2 

RcadProcessState 27-4 

Ready 27-7 

Realloc 24-1 

RcccivcSpccific 27-11 

RcccivcWithScgment 27-11 

Rectangle 29-6 

Rectangles 10-1 

Redraw 2-8 

RcdrawPad 29-5 

Reference Line 29-6 

Register Handler 37-1 

Release Instance 33-5,46-3 

RclcascArgumcntSpinLock 23-2 

RclcascGlobalSpinlxjck 23-2 

Rclcasclnstance 22-4 

RclcascSpinLock 23-1 

Remote execution 42-1 

Remote program execution 3-3,3-4,3-6 

Rcmotcl-xccute 28-3 

RcmovcRlc 22-8 

Rename 4-6 

Rename File 34*9 

Rename Object 34-9 

Reply 27-11 

Reply code 32-1 

RcplyWilhScgmcnt 27-11 

Report Click 29-3 

Report Transition 29-3 

Request code 32-1 

Request Message Formats 33-3 

Request Not Supported 32-4 

Reset State 2-8 

RcsctTTY 29-14 



ResolvcLocalName 25-2 
Resynch 22-5 
Retry 32-4 
Retry Unicast 32-4 
Return 46-1 

RcturnModificdPages 27-4 
Reverse Index 46-2 
Right Mouse Button 14-7 
Rindex 30-2 
Rlog 4-6 
Rm 4-6 

Root process 18-1 
Round-robin scheduling 42-1 

SameTeam 27-4 

Screensaver 2-7 

Scribe 10-1.10-6,10-9 

Scroll Region 46-2 

SDF 29-5 

Seek 22-4 

ScekBlock 22-6 

Segment 27-12 

Selected Horizontal Reference line 29-7 

Selected Vertical Reference line 29-7 

SclcctionRec 28-3 

SclcctPad 29-15,46-4 

Send 27-11 

Serial 4-7 

Serial line 36-3 

Server Not Responding 32-4 

Services 31-1 

Sessions 43-1 

Set Alternate face Size 2-8 

Set Break Process 33-7.46-3 

Set Instance Owner 33-7,46-3 

Set Prompt 33-8 

SctBrcakProccss 22-9.46-5 

Sctcnv 25-5 

ScllnslanccOwncr 22-9 

Sctjmp 30-4 

SctObjcctOwner 27-5 

SctPid 27-5 

SctProccssl»riority 27-5 

SctTcaml > riority 27-5 

SctTcamSizc 27-5 

SctTime 30-1 

SctUpl ; .nvironmcnt 18-4 

SctUscrNumbcr 35-3 

SelVglBanncr 29-15,46-4.46-5 

SGVI' 2-3.29-5 

Shell 3-1 

ShiRIn 46-1 

ShiR Out 46-1 

Shiftjca 30-3 

Show 4-7 

SIL 10-1 

Silcdit 4-9.12-1 

Silprcss 4-9.12-3 

SimpleText 29-7 

Size 30-3 
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Sleep 4-7.30-2 

SMI 2-4 

Sort 4-7 

Special Vcd commands 14-2 

SpecialGose 22-4 

Spin locks 2M 

Spline 29-7 

Splines 10-1 

Srand 26-1 

Stack overflow 18-1 

Stack size 18-1 

Standard&tccptionHandler 30-4 

Start of Line 2-10 

Startcxcc 4-7 

Starting up Vcd 14-1 

Stime 30-1 

Storage server 31-5 

St^ragcstats 4-7 

Oixcat 30-2 

Strcmp 30-2 

Strcpy 30-2 

Stream 22-2.33-1 

Strings 30-2 

Strien 30-2 

Strncat 30-2 

Stmcmp 30-2 

Strncpy 30-2 

Strsave 30-3 

Structured display file 29-5 

Structured Graphics 10-9 

Structured graphics virtual terminal 2-3, 29*5 

STS 3-1 

STS hardware environment 45-1 

STS line editing 45-1 

Stuffboot 4-7 

Style B-l 

Su 3-3 

Subprograms 18-2 

Suicide 27-8 

SunlOOvgts 46-1 

Sunl20vgts 46-1 

Swab 24-2 

SwaplKPackct 32-1 

Switch Input 46-4 

Symbol 29-5 

System 28-4 

SystemCode 27-8 

Tab 2-10,46-1 

Tail 4-7 

Talk 4-7 

TCP/IP 39-1 

Team environment block 18-3, 18-4 

Team leading 31-5, 42-1 

Team ownership 42-1 

Team root message 18-3 

Team server 31-3, 42-1 

TcainRout 18-2, 18-3 

Telnet 4-8.45-2 

Telnet server 4-8 



Terminal agent 2-1,3-1 

Terminal emulation 29-1 

Terminal Emulator 46-1 

Termination 31-6 

Tcstexccpt 4-8 

Text 10-1 

Time 17-3.30-1 

Timcipc 13-1 

Timeipcscrvcr 13-1 

Timekernel 4-9 

Timeout 32-4 

Timezone 30-1 . 

Toggle Grid 2-9 

Toggle Paged Output Mode 2-9 

Tops-20 3-1 

TransferHost 27-7 

Transition 2*7 

Transpose 2-10 

Transpose Words 45-1 

Tsort 4-9 

Type 4-9.22-2 

Types 3>1 

Un-Kill 45-1 
Undefine 4-9 
UndefincLocalName 25-2 
UnfreezeHost 27-7 
Unix 3-1.3-3.4-9,17-1 
Unix server 43-1 
Unlink 22-9 
Upper 30-3 
User 35-3 

UscrCorrcspondences 43-1 
UscrName 35-3 

V server 3-3,43-1 

ValidPid 27-6 

Variable Block 22-2,33-2 

Vax 4-9 

Vcd 4-9.14-1 

Vcd buffers 14-6 

Vcd crash recovery 14-12 

Vcd cursor motion 14-2 

Vcd editing commands 14-3 

Vcd file access 14-5 

Vcd kill buffer 14-3 

Vcd mark 14-4 

Vcd mouse 14-7 

Vcd paging 14-3 

Vcd region 14-4 

Vcd replacing 14-5 

Vcd scrolling 14-3 

Vcd searching 14-5 

Vcd special characters 14-3 

Vcd windows 14-6 

Vcmacs 4-9 

Vcnviron.h 18-1.32-2 

Verbs 10-2.104 

Vertical Line 29-8 

Vertical Reference line 29-8 
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Vcthcrncth 36-1 

Vcxccptions.h 37-1 

VGT 2-3 

VGTS 3-l,9-U4frl 

Vgts.h 29-17 

View 2-2 

View Manager 3-1.46*3 

View Manager Menu 2-7 

Vio.h 33-1 
VioprotocoLh 33-3 
Virtual graphics terminal 2-3 
Virtual terminal 2-1,2*3 
Vload 16-1,18-2 
VmouscJt 36-2 
Vpassword 35-4, C-5 
Vspinlocth 23-1 
Vtcams.h 28-3 
Vtermagcnth 29-17 
Vuscrcorrcspndencc C-5 

W 4-9 

Wait 28-2 

Wakeup 30-1 

Wc 4-9 

Wh 4-9 

Whi 4-9 

Who is logged in 4-5,4-9 

Workstation agent 31-3 
Write 22-6 

Write Descriptor 34-10 
Write Instance 33-6,46-3 
Writcable 22-2,33-1 
WritcDcscriptor 252 
WriicProccssStatc 27-6 
Writcshort Instance 46-3 

Xerox 10-1 

Yale 4-3 

Zero 24-2,29-6 
Zoom 2-9 
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